home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr30
/
clock347.zip
/
CLOCK.DOC
< prev
next >
Wrap
Text File
|
1993-04-26
|
188KB
|
5,149 lines
CLOCK
Version 3.47
CLOCK is a shareware program.
See Appendix A for registration information.
$10 (or $25 for full source code)
Ronald Q. Smith
11 Black Oak Road
North Oaks, MN 55127-6204
(c) Copyright 1991-1993 Ronald Q. Smith
CLOCK Version 3.47 April 10, 1993
CONTENTS
1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . 1
1 CLOCK.SYS - Replacement Device Driver . . . . . . . . . . 3
1.1 Unique Clock Hardware Support . . . . . . . . . . . 3
1.2 Installing CLOCK.SYS . . . . . . . . . . . . . . . 4
1.3 Clock Type . . . . . . . . . . . . . . . . . . . . 8
1.4 Examples . . . . . . . . . . . . . . . . . . . . . 11
1.5 Future Enhancements . . . . . . . . . . . . . . . . 11
2 CLK.EXE - Clock Control Program . . . . . . . . . . . . . 12
2.1 CLK Command . . . . . . . . . . . . . . . . . . . . 12
2.2 Format of TZ= Function . . . . . . . . . . . . . . 24
2.3 Using CLK . . . . . . . . . . . . . . . . . . . . . 27
2.4 Examples . . . . . . . . . . . . . . . . . . . . . 30
2.5 Errors . . . . . . . . . . . . . . . . . . . . . . 31
2.6 Future Enhancements . . . . . . . . . . . . . . . . 31
3 CLKDEMO.EXE . . . . . . . . . . . . . . . . . . . . . . . 33
3.1 CLKDEMO Command Line . . . . . . . . . . . . . . . 33
4 IOCTL - API TO CLOCK.SYS . . . . . . . . . . . . . . . . . 34
4.1 Data Structures . . . . . . . . . . . . . . . . . . 34
4.2 clksta . . . . . . . . . . . . . . . . . . . . . . 37
4.3 setpw . . . . . . . . . . . . . . . . . . . . . . . 40
4.4 connec . . . . . . . . . . . . . . . . . . . . . . 41
4.5 newpw . . . . . . . . . . . . . . . . . . . . . . . 43
4.6 rstrct . . . . . . . . . . . . . . . . . . . . . . 44
4.7 stmode . . . . . . . . . . . . . . . . . . . . . . 47
4.8 stzone . . . . . . . . . . . . . . . . . . . . . . 48
4.9 tdisp . . . . . . . . . . . . . . . . . . . . . . . 51
5 CLOCK.SYS - ASSEMBLY LANGUAGE API . . . . . . . . . . . . 55
5.1 Opening the CLOCK$ Device . . . . . . . . . . . . . 55
5.2 Sending New Values to CLOCK.SYS . . . . . . . . . . 55
5.3 Getting Current Status of CLOCK.SYS . . . . . . . . 57
APPENDIX A: DEFINITION OF SHAREWARE . . . . . . . . . . . . 58
APPENDIX B: CLOCK TYPES . . . . . . . . . . . . . . . . . . 60
B.1 Type 0 - PC/AT . . . . . . . . . . . . . . . . . . 60
B.2 Type 1 - Zenith Z-18x portables, Supersport 20 . . 61
B.3 Type 2 - Various Zenith Data System PCs. . . . . . 61
B.4 Type 3 - Memory-Mapped Clocks . . . . . . . . . . . 62
B.5 Type 4 - Direct Register I/O Bus Clock . . . . . . 63
B.6 Type 5 - Mitsubishi 8088 PCs . . . . . . . . . . . 64
ii
CLOCK Version 3.47 April 10, 1993
B.7 Type 6 - Indirect Register I/O Bus Clock . . . . . 66
B.8 Type 7 - Complex I/O Bus Clock . . . . . . . . . . 67
B.9 Type 8 - Generic I/O Bus Clock . . . . . . . . . . 68
B.10 Type 9 - Quadram I/O Bus Clock . . . . . . . . . . 68
B.11 Type A - AT&T 6300, 6300 PLUS, 6300 WGS . . . . . . 69
B.12 Type B - Hyundai 8088 clock . . . . . . . . . . . . 70
APPENDIX C: REVISION HISTORY . . . . . . . . . . . . . . . . 71
iii
CLOCK Version 3.47 April 10, 1993
1 INTRODUCTION
CLOCK consists of two programs that give you complete control
over the operation of your calendar (battery-protected) clock and
your DOS/BIOS internal timer. The normal DOS mode of operation
is to read the calendar clock when you boot the system and set
the internal timer. Thereafter all read operations refer only to
the internal timer while time setting operations write to both
clocks. In levels of DOS prior to 3.3, even time setting opera-
tions only wrote to the internal timer. In order to set the
calendar clock you had to run the SETUP program.
Some of the drawbacks to the standard DOS clock operation that
the CLOCK programs address are:
∙ There is no provision to switch time zones without
resetting the system time.
∙ DOS does not handle automatic changes between daylight
savings time and standard time.
∙ The DOS/BIOS internal timer often drifts quite rapidly
away from the time maintained by the more accurate
calendar clock.
∙ Even the calendar clock drifts slowly away from the
accurate time. DOS provides no way to automatically
adjust for that drift.
∙ If your battery is failing or some other hardware or
software problem messes up the time in your calendar
clock, there is no way to detect that except by manual-
ly displaying the time and checking it.
∙ If you have to run a program that occasionally changes
the time incorrectly, there is no way to protect your
clock from those changes. You can also have this
problem if you are a parent whose children set the
clock when you don't want them to, an instructor whose
students reset the time, or an expert young user whose
parents mess up your clock.
∙ If you need to experiment with special times and dates
but don't want to have to reset your clock afterwards,
DOS has no mechanism to help. In order to test end-of-
month processing for your application, you have to set
the date and time, run your tests, and then set the
time and date back.
1
CLOCK Version 3.47 April 10, 1993
∙ The standard DOS and BIOS software on some PCs can miss
the change to a new day when the PC is left on over
midnight.
∙ Your clock might not handle automatic changes to a new
year or may not understand leap years.
∙ You may have an older PC from before the PC/AT clock
standardization and your vendor no longer releases new
versions of DOS for that PC. You are stuck on DOS 3.2
or earlier or you have to give up your calendar clock.
If any of those circumstances cause problems for you, CLOCK can
help. The two primary programs are CLOCK.SYS and CLK.EXE. In
addition, if you are a software developer, CLKDEMO is provided in
source code to show you how to program the extended clock opera-
tions into your own applications.
CLOCK.SYS is a clock device driver (CLOCK$ device). It
replaces the DOS internal clock driver. CLOCK.SYS pro-
vides for automatic time zone conversion. It also
allows you to periodically or continuously get the time
from the calendar clock. This can totally eliminate
problems with missing day changes and realtime clocks
that are inaccurate. CLOCK.SYS provides support for
many types of calendar clocks including many of the
original add-in clocks of the 8088 era. If your clock
is not currently supported, I want to hear from you. I
will be happy to add it to the software.
CLK.EXE is a program that allows you to separately
control your DOS/BIOS internal clock and battery-pro-
tected calendar clock. Most importantly, CLK.EXE will
handle time zones and will automatically switch between
standard and daylight savings time for you. It also
supports automatic adjustment for calendar clock drift,
checks for incorrect or unlikely times, and can re-
strict time changes.
CLKDEMO.EXE is a small part of CLK.EXE that is provided
in source code (C language) form so that you can see
how to add clock control to your own applications.
2
CLOCK Version 3.47 April 10, 1993
1 CLOCK.SYS - Replacement Device Driver
CLOCK.SYS is a device driver that replaces the built-in CLOCK$
device driver in DOS levels 2.1 and above. CLOCK.SYS adds many
functions not provided in the standard DOS CLOCK$ device driver.
You won't see mention of the DOS CLOCK$ device driver in your DOS
user's guides. You will see a very small mention of it in the
system's programmers reference manuals if you are an assembly
language developer. It is there and DOS was specifically de-
signed to let you replace it with one of your own even if the
manual doesn't tell you that.
1.1 Unique Clock Hardware Support
CLOCK.SYS was originally written especially for those people
whose clocks are not supported by new levels of DOS. This
usually occurs because your vendor stopped providing new levels
of DOS adapted for your computer model. Before the days of the
PC/AT and standard clock interfaces, DOS was usually sold direct-
ly to hardware vendors who customized it for their system and
delivered it with the system. In addition, many of the early
clocks were provided by third-party, after-market vendors who had
no idea what system it would be used in. Since those systems and
clocks have been out of production for a long time, most of the
vendors have stopped providing upgrades. Yet most of those PCs
will happily run DOS 3.3 or above and especially DOS 5.0 except
that you have to give up your calendar clock.
CLOCK.SYS supports a wide variety of different clock hardware and
BIOS interfaces. As far as possible, CLOCK.SYS will automatical-
ly determine what clock interface to use. If the automatic
determination does not work for your system, you may tell
CLOCK.SYS specifically what interface type to use. CLOCK.SYS is
also required by anyone who wants to use CLK as it provides
functions not provided by the normal DOS CLOCK$ device driver.
CLOCK.SYS is fully compatible with the DOS device driver on all
modern PCs and many older ones.
If your PC clock is not currently supported but you would like to
remove the restrictions on what versions of DOS you can use,
please contact me by mail or on CompuServe. I will be happy to
add support for your clock. I will need some technical informa-
tion and help from you in getting it to work so I will give you a
$0 usage license for your help. Please see section 1.3 for the
current list of supported clocks and Appendix B for a description
of those clocks.
3
CLOCK Version 3.47 April 10, 1993
1.2 Installing CLOCK.SYS
To install the device driver include the following line in your
CONFIG.SYS file.
Syntax device=[d:][path\]clock.sys [type][,io_addr] [/N]
or
device=[d:][path\]clock.sys 3[,segment[,write0,
write1,read]] [/N]
or
device=[d:][path\]clock.sys A[,base_year] [/N]
Parameters d:
Identifies the drive containing CLOCK.SYS. If d:
is not provided, the boot drive is assumed.
path\
Specifies the directory containing CLOCK.SYS. If
path\ is not given, the root directory is assumed.
CLOCK.SYS
Is the name of the CLOCK.SYS file. You may change
the name if you wish, but you must not use the
.COM or .EXE extensions.
type
Is the kind of calendar clock on your system. If
you do not provide type, CLOCK.SYS will probe your
system to determine which clock you have.
CLOCK.SYS is usually able to detect the type of
calendar clock without trouble. It is possible,
however, that you have some other hardware in your
system that could fool CLOCK.SYS. For that rea-
son, you might need to provide the type of clock.
See section 1.3 and Appendix B for more informa-
tion about the clock types.
io_addr
Is the I/O bus address of your clock hardware.
Some of the types of clocks that are supported
were set up at a wide variety of I/O addresses.
CLOCK.SYS probes all the commonly used I/O ad-
dresses for these clocks. However, you or your
4
CLOCK Version 3.47 April 10, 1993
vendor may have installed your clock at an address
that CLOCK.SYS doesn't know about. By providing
the address, you make it much more likely that
CLOCK.SYS will correctly find your clock. Even if
you don't know what type of clock you have, pro-
viding the I/O address may be enough for CLOCK.SYS
to determine which one it is. io_addr is current-
ly used with clock types 4, 6, 7, 8, 9, and B.
Normally this is 240, 2C0, or 340 for types 4, 6,
and 7. It is 210 or 310 for type 9. And it is E0
for type B. All numbers are in hex. For example,
an AST Research clock might be:
device=[d:][path\]clock.sys 4,2C0
If you do not specify the "io_addr", CLOCK.SYS
will try to determine the correct address by prob-
ing.
If you are sure that you have an I/O clock but you
are not sure which one it is, specify type 8 and
supply the io_addr if possible. Type 8 does not
represent a specific clock. Rather it attempts to
determine whether your clock is a type 4, 6, 7, 9,
or B using a sequence of tests similar to those
used by some of the I/O clock vendors to figure
out what kind of clock you have.
If you have a memory mapped clock, you may use the
second format to specify the addresses to be used. If
you don't know the addresses, CLOCK.SYS will attempt to
determine them by probing.
segment
Is the base address used to access the clock.
Usually your documentation will give the segment
address as four hex digits such as FE00 or F000.
Some addresses may be less than four digits (e.g.,
70). Other documentation may show addresses in
the form aaaa:bbbb. In this case the segment
address is the aaaa value. Sometimes these ad-
dresses are written as 0xaaaa, aaaah, aaaaH, or
0Xaaaa. In all of these forms there is a 2- to 4-
digit hex number that is the segment address.
write0
Is the offset used to write 0 bits. It must also
be a hex address and may be 0, F002, or anything
5
CLOCK Version 3.47 April 10, 1993
else the vendor chose. If the addresses are given
in the aaaa:bbbb form, use the bbbb. With these
clocks, you read and write the clock by reading
the memory addresses. For example, reading ad-
dress segment:write0 results in writing a zero bit
to the clock. Writing an appropriate length se-
quence of zero and one bits sets the clock.
write1
Is the offset used to write 1 bits.
read
Is the offset used to read bits.
If your documentation gives the segment address
but isn't clear about the offsets, just specify
the segment address and CLOCK.SYS will try all
offset combinations that it knows about.
If you specify one of the offsets, you must speci-
fy them all.
The third format is used with the AT&T 6300 clocks.
base_year
Is used for the AT&T 6300 clocks (type=A). Dates
prior to that year or more than 7 years after that
year will not be handled correctly. If no base
year is specified, 1992 will be used. Dates be-
tween the start of the base year and the end of
the seventh year later are handled (e.g., 1992-1-1
until 1999-12-31).
/N
Indicates that you do not want CLOCK.SYS to at-
tempt to detect missed date changes. Normally
CLOCK.SYS will try to detect when a date has
changed that was not reported by the BIOS. This
usually happens when a program is running past
midnight and calls the BIOS to read the time rath-
er than calling DOS. That program sees the date-
change indication from the BIOS and DOS
(CLOCK.SYS) never gets a chance to change the day.
However, the logic that CLOCK.SYS uses can be
fooled by programs that change the time with di-
rect calls on the BIOS and may advance the date
incorrectly. This is very rare, but if your date
6
CLOCK Version 3.47 April 10, 1993
advances unexpectedly or by more than one day, you
may want to use this option.
Notes DOS interfaces ______________
All DOS DATE and TIME commands and all DOS date and
time system calls will operate with no apparent change
to you or any program. Unless you have used CLK to
change the time handling, your clocks are handled just
as DOS would handle them.
Dates and leap years ____________________
CLOCK.SYS supports all valid DOS dates from 1980-1-1 to
2079-12-31. It supports dates to 2099-12-31 for many
of the clocks. CLOCK.SYS also handles year changes and
leap years automatically for clock types that don't do
it themselves.
Time zones and daylight savings time ____________________________________
CLOCK.SYS in conjunction with CLK.EXE provides support
for multiple time zones and automatic conversion be-
tween daylight savings time and standard time at the
appropriate times of the year. For this reason,
CLOCK.SYS may be of great use to you even if your
version of DOS already supports your clock correctly.
Clock synchronization _____________________
Normally, CLOCK.SYS operates identically to the DOS
CLOCK$ device driver. At boot it sets the DOS clock
from the calendar clock. Any time you change the date
or time it writes to both clocks.
With CLK.EXE you have several other options. If you
have specified a time zone and offset with CLK.EXE,
CLOCK.SYS will adjust all times read from and written
to the calendar clock by the time zone offset. You can
also set it to read the calendar clock rather than the
DOS clock for some or all time requests to ensure
continued synchronization of the two clocks. You can
also totally separate the two clocks so that DOS time
and date functions only read and write the DOS/BIOS
internal clock.
Time setting limits ___________________
CLK.EXE can tell CLOCK.SYS to apply limits to the time
changes that it will accept or stop accepting time
changes at all. For example, you can tell CLOCK.SYS to
accept no changes that would set the clock backward.
You can also inhibit all changes.
7
CLOCK Version 3.47 April 10, 1993
Password Protection ___________________
CLK.EXE can establish a password to control future
changes to the time zone, connection, and time setting
limits. Once the password is set, all attempts to
change those values will simply be ignored unless the
correct password is supplied. You may change the
daylight versus standard time flag and the continuous
time display without knowing the password.
Continuous Time Display _______________________
CLK.EXE can tell CLOCK.SYS to display the time continu-
ously at any position on your screen. You specify the
cursor coordinates, display attributes, and 12-hour or
24-hour mode and CLOCK.SYS will update the display
every second.
Saving Settings Across Boots ____________________________
With CLK.EXE you can save the current state of
CLOCK.SYS at any time in a form that can be used on
your next boot. You can set up your time zone, setting
limits, connection mode, continuous display, and pass-
word and then save a new version of CLOCK.SYS. This
new version will automatically start running with
without having to scan for your clock type and with all
your standard state automatically in effect.
1.3 Clock Type
There are almost as many different implementations of PC clocks
as there are different types of PCs. Until the PC/AT came along,
there was no standard for battery-protected clocks, and each PC
and add-in vendor was likely to implement them differently. With
the PC/AT a standard and documented interface for such clocks was
provided. Since that time, most PCs have followed the PC/AT
standard. It is earlier PCs, especially 8088 PCs, that don't
follow the standard. Since these are early PCs, there is also a
high probability that the vendor is no longer providing modified
versions of DOS with built-in support for their clocks. Most
add-in clock vendors never did provide a modified DOS and you had
to manage your clock with utility programs. This leaves you
faced with the choice between staying with an early version of
DOS or giving up your clock.
CLOCK.SYS is intended to free you from those limitations. It
will work with all versions of DOS from 2.10 through 5.00 and
undoubtedly beyond. It also attempts to automatically determine
what kind of clock you have and install the correct support for
8
CLOCK Version 3.47 April 10, 1993
it. However, there are often enough differences between PCs that
the automatic determination may not find anything or may even
make the wrong choice. To give you more control of the situa-
tion, you may specify the clock interface by giving an interface
number.
It will not always be easy to decide what interface number to
use. You will at least need some technical information on how
your clock works or on the BIOS calls used to control the bat-
tery-protected clock. If you find a description below that seems
to match, give it a try. The most that should go wrong is that
your time and date will be set incorrectly, but then they proba-
bly weren't working anyhow.
If you aren't sure what interface to use or if you are sure that
your clock is not supported, LET ME KNOW. I WOULD LIKE TO HELP.
You can help me make CLOCK.SYS better for everyone. I would even
like to hear from you if CLOCK.SYS did work for you and your
clock isn't currently listed. I would like to be able to add
your PC manufacturer and model number to the supported list so
others know what to use. If CLOCK.SYS did not work for you, I am
interested in making the changes so that it does work. If you
can provide me with the necessary technical information, I will
make the changes.
Usually, a technical reference manual with hardware and BIOS
interfaces is the best source. Even if you don't have one, your
original hardware vendor may be willing to send you enough
information to allow you to program the clock. If all else
fails, we may even be able to use an old copy of DOS or a clock
setting utility to figure out how it works. Before we do that,
check your license to be sure that it is not forbidden to disas-
semble the software to see how the clock works.
The following table shows the systems that have been determined
to work with existing clock types. If your system is in the
list, try the clock type indicated. If not, look through Appen-
dix B which tells you about the characteristics of each type of
clock and see if anything seems to match your system type.
9
CLOCK Version 3.47 April 10, 1993
╔═══════════════════════════╤══════════════════════════╗
║ SYSTEM │ BLOCK TYPE ║
╟───────────────────────────┼──────────────────────────╢
║ Amstrad PC1521DD │ 0 ║
╟───────────────────────────┼──────────────────────────╢
║ AST Research │ 8 (4, 6, or 7) See dis- ║
║ Six-Pack │ cussion above and in ║
║ I/O Plus │ Appendix B ║
║ etc. │ ║
╟───────────────────────────┼──────────────────────────╢
║ AT&T 6300 │ A ║
╟───────────────────────────┼──────────────────────────╢
║ Hyundai 8088 │ B ║
╟───────────────────────────┼──────────────────────────╢
║ IBM PC/AT and most │ 0 ║
║ PCs since then. │ ║
╟───────────────────────────┼──────────────────────────╢
║ Leading Edge Model D │ 5 ║
╟───────────────────────────┼──────────────────────────╢
║ Mitsubishi 8088 │ 5 ║
╟───────────────────────────┼──────────────────────────╢
║ Quadram Corp. │ 9 ║
║ QuadCard │ ║
║ QuadCard II │ ║
║ QuadCard 512+ │ ║
╟───────────────────────────┼──────────────────────────╢
║ SMT No-Slot Clock │ 3 ║
╟───────────────────────────┼──────────────────────────╢
║ Sperry PC-1 │ 5 ║
╟───────────────────────────┼──────────────────────────╢
║ Sperry PC/HT │ 5 ║
╟───────────────────────────┼──────────────────────────╢
║ Tandy 1200HD │ 4 ║
╟───────────────────────────┼──────────────────────────╢
║ Vendex Turbo-888-XT │ 4 ║
╟───────────────────────────┼──────────────────────────╢
║ Zenith Supersport 20 │ 1 ║
╟───────────────────────────┼──────────────────────────╢
║ Zenith Z-18x │ 1 ║
╚═══════════════════════════╧══════════════════════════╝
10
CLOCK Version 3.47 April 10, 1993
1.4 Examples
For almost everyone, the only format you ever need to use is:
device=[d:][path\]clock.sys
If CLOCK.SYS is in the root directory of your boot device, this
is:
device=clock.sys
CLOCK.SYS will quite happily load into the upper memory blocks
(UMBs) provided by DOS 5.0 and by other software. With DOS 5.0,
you might use:
devicehigh=clock.sys
With some memory managers you can even load CLOCK.SYS into upper
memory blocks on earlier levels of DOS. See your manual for the
commands to use. Some of these memory managers will create UMBs
on 8088 and 80286 systems. CLOCK.SYS loads and runs high on
those systems as well.
With a memory mapped clock that uses an address combination that
CLOCK.SYS doesn't search automatically and with CLOCK.SYS stored
in the C:\UTILITY directory, you might use:
device=c:\utility\clock.sys 3,ffff,f000,f004,f008
Please note that the memory addresses chosen for this example are
not likely to match those of your clock and you should substitute
the addresses appropriate to your clock.
If you have an I/O clock with the same interface as the Quadram
Corp. clock but a different I/O address, you might use:
device=clock.sys 9,3fc
if your I/O base address were 3fc.
If you have one of the AT&T 6300 system types and you occasional-
ly need to set your clock prior to 1992-1-1, you might use:
device=clock.sys a,1988
1.5 Future Enhancements
Of course, I hope to add more clocks as people ask for them.
Those old PCs are still good for a lot of what we do even if they
are sometimes relegated to a secondary status.
There are no other outstanding enhancements currently planned for
CLOCK.SYS.
11
CLOCK Version 3.47 April 10, 1993
2 CLK.EXE - Clock Control Program
CLK gives you complete control over the operation of the calendar
clock and DOS/BIOS clock. You can operate them separately or
together. You can establish time zones, daylight savings time
rules, automatic adjustment, synchronization rules, and more.
2.1 CLK Command
Syntax clk [function] [function ...] [/I[file]] [/?]
or in full form
clk [A=±sss.cc] [C=A|D|R|W] [D=[N][x,y,a[,12|,24]]
[L=...] [M=...] [R=A|B-hh:mm:ss|F+hh:mm:ss|N|R]
[S=C|D] [TZ=...] [W=-back,+forward] [/B]
[/I[file][,C]] [/M[file][,C]] [/P[N]] [/S[file]]
[/?]
Parameters function
There are many functions that may be used with
CLK.EXE and they are discussed in the following
paragraphs. You may use any number of functions
on a single command line and they will be pro-
cessed in the order in which you enter them.
However, if any error is discovered in any of the
functions, none of them are processed. Thus,
clk c=r tz=:est
is the same as the two command lines:
clk c=r
clk tz=:est
except that an error in either of the functions in
the first example cause the whole command to be
ignored.
The case (upper or lower) of any of the function
names, options, or values is ignored except for
the TZ function's time zone names. Even there,
the case is not used. It is simply preserved for
later display.
You can display a help message about any function
or option by immediately following the function
letter or option letter with ?. Thus M? displays
help about the M= function and /I? displays help
about the I option. /? displays a help message
about the CLK command line.
12
CLOCK Version 3.47 April 10, 1993
none
If no function or option is provided, CLK displays
the current state of operation of CLOCK.SYS and
the current time from both the calendar clock and
the DOS/BIOS clock.
If you have used CLK to set a time zone (TZ func-
tion), the current time zone name and offset value
are displayed. These values are saved in
CLOCK.SYS so that they may be used for time func-
tions.
The connection state of the clocks (C function) is
displayed as is the current restrictions (R func-
tion) on clock changes.
All uses of CLK (except errors and /?) end by
displaying the same information. You always know
the state of your two clocks after execution.
A=±sss.cc
The Adjust function is used to set a daily adjust-
ment factor in seconds and 100ths of seconds.
This function assumes that you have some knowledge
of the rate at which your calendar clock drifts
with respect to "real" time. Presumably you have
periodically set your clock using a program that
calls the Naval Observatory or NIST and noted the
difference over time. Some such programs will
help you to calculate the drift rate. You can get
a very good adjustment from a decent quartz watch.
The value may be a positive or negative number in
the range -326.99 to +326.99 seconds per day but
reasonable values are likely to be a fraction of a
second.
The first time you use A=, your clock is not ad-
justed. The value of A and the current time are
saved in a file for later use. Later you can
choose to run CLK with the /I option to invoke the
file. The elapsed time since the last adjustment
(or the time you last changed A) in days and frac-
tions is multiplied by A to calculate any adjust-
ment that needs to be applied. Only whole seconds
of adjustment are applied.
13
CLOCK Version 3.47 April 10, 1993
The A= function only sets the adjustment factor.
The actual adjustment is carried out by the L=
function. You don't have to enter the L= func-
tion. CLK will do that for you the first time you
use A= and will keep it up to date as it later
makes adjustments.
NOTE: Do not use the A= function with the AT&T
6300 clocks (Type A) or the Quadram clocks (Type
9). They only permit the time to be set to the
nearest minute.
C=A
Connects the two clocks for All operations. All
read operations go directly to the calendar clock.
The calendard clock is read, the time is adjusted
for any time zone offset, and the adjusted time is
written to the DOS clock and returned to the call-
er. With this function, your calendar clock es-
sentially becomes the only clock. However, the
DOS clock is set each time so that any application
reading the clock directly (without going through
DOS) sees the same time that DOS reports. It is
unwise to use this function if your clock is slow
(some I/O clocks and some memory-mapped clocks) or
if it only increments in units of seconds (most
clocks). Any time zone offset is applied to reads
and writes.
C=D
Disconnects the two clocks. Any change of the
date and time will affect the DOS clock only.
Reads also use the DOS clock only. This function
allows you to perform any operation on the time
without affecting your calendar clock. It is
useful for dealing with ill-behaved programs that
need to change the time and for testing programs
at different dates and times. You can later use
the C=R, C=A, or other functions to re-establish
the value in your DOS clock from the calendar
clock.
C=R
Connects the two clocks for writing and periodic
Reading. This function may be used when your
clocks drift slowly with respect to each other.
If the time has not been read for about 10 sec-
onds, the calendar clock will be read, adjusted by
14
CLOCK Version 3.47 April 10, 1993
the offset if any, and the adjusted time written
to the DOS clock and returned to the caller. This
periodic Read assures you that the clocks never
get very far out of synchronization with each
other. Some calendar clocks take a relatively
long time to read and most don't have 100ths of
seconds. By only reading the calendar clock when
no other time request has occurred in the last 10
seconds, we minimize both the overhead and any
visibility of time jumps.
C=W
Connects the two clocks for Writing. This is the
default mode of operation and is the same mode
that the DOS CLOCK$ device driver supports as its
only mode. Reading the time is served by the DOS
clock. Writing the time sets both clocks. If a
time zone offset has previously been specified,
all writes to the clock are adjusted so that the
calendar clock remains on the base time. For
example, if the calendar clock is set to UTC and
you specify that you want to use CST which has an
offset of 6 hours from UTC, all writes of the time
will have 6 hours added to them before writing to
the calendar clock. Thus the DOS clock and the
calendar clock remain at a constant time offset.
D=N
The D= function controls a continuous time dis-
play. D=N turns off the continuous display.
D=x,y,a[,12|,24]
Starts a continuous time display at cursor posi-
tion x,y with display attribute a. Cursor posi-
tion 0,0 is the upper left corner of the screen.
The typical screen format runs from 0,0 to 79,24.
The display attribute is a two-digit hex number
that gives the background and foreground colors.
The high-order digit is the background color (0 to
7 usually) and the low-order digit is the fore-
ground or character color (0 to F). The default
display is a 24-hour clock in the form HH:MM:SS.
If you add the ",12", the display will use a 12-
hour clock. No AM or PM indication is given.
D=72,24,79,12 will place the display at the right
edge of the last line of most screens. The text
15
CLOCK Version 3.47 April 10, 1993
will be in bright blue on a white background and
the hours will run from 12 through 11.
D= by itself will resume a previous display that
was turned off by D=N. You do not have to re-
enter all the values.
The D= functions should not be used if CLK is
executed from within Windows. If you try to do
so, you will received an error message. This
avoids a hung system which would occur if CLK
didn't check.
L=YYYY-MM-DD,hh:mm:ss,±sss.cc
The L= function is not intended to be used on the
command line, but will be accepted if you provide
it. The L= function is normally created by CLK
and saved in the CLK.INI file for later use in
processing adjustments. The date and time of the
last adjustment (or the most recent time you gave
an A= function on the command line) are given by
the YYYY-MM-DD,hh:mm:ss. Any non-digit except a
space may separate the sub-fields. The date and
time must be followed by a comma and any adjust-
ment remainder. The adjustment remainder is in
the same form as the value for the A= function but
will usually be a fraction of a second. It is the
adjustment that was left over the last time an
adjustment was actually made since only whole
seconds of changes are made to the clock.
The L= function triggers an adjustment if needed.
Generally, it will follow the A= function that
sets the adjustment factor. Both of these func-
tions normally appear in the CLK.INI file.
The L= function may also be used by itself to do
simple arithmetic on the clocks. Use it on the
command line with any earlier date and time and an
adjustment of the number of seconds (positive or
negative) that you want added to the clock. The
change will be made and the last adjustment time
set to the current time. For example,
clk l=1990-1-1,0:0:0,-4
will subtract 4 seconds from the clocks.
16
CLOCK Version 3.47 April 10, 1993
M=±sss.cc,YYYY-MM-DD,hh:mm:ss
The M= function is used to help you calculate the
automatic adjustment A= value for your calendar
clock. The M= function is used to enter the manu-
al adjustments that you make to the clock in addi-
tion to the automatic adjustments. The ±sss.cc is
the amount of manual adjustment that you have
made. This may be adjustments made by setting the
clock with the DOS DATE and TIME commands or ad-
justments made by a time setting program. The
YYYY-MM-DD,hh:mm:ss is the date and time at which
the adjustment was made. It is very important
that the date and time be given with respect to
the calendar clock and not the DOS clock, if dif-
ferent. If you do not supply the date and time,
the current date and time will be used. This
should be sufficiently accurate if you just com-
pleted making the adjustement.
The first M= value that you enter is used only to
set a base date and time. Then as you enter addi-
tional values in the future, CLK will calculate a
new value for the A= function by adding the aver-
age manual adjustment per day to the current A=
value. Up to 8 values are saved in the CLK.INI
file (or other file that you specify). The more
values you provide and the longer the time period,
the more accurate the adjustment will be. For
example, if you can only determine the adjustment
to the nearest second (likely), you may want to
have a week or more between manual adjustments.
The only restriction is that the first and last
manual adjustement must be within one year of each
other. If you enter more than 8, the oldest two
adjustement values are collapsed into a single
value.
Supplying a new A= value, presumably based on the
calculations from CLK, deletes all the M= values
from the file. You may either specify a /I option
to specify the file and read all the functions in
the file, a /M option to specify the file and only
read the M= functions, or CLK will automatically
specify the /M option for you (but it will only
know to look for CLK.INI in the directory contain-
ing CLK.EXE). You may also edit the M= functions
in the file and use the /M option to force a re-
calculation.
17
CLOCK Version 3.47 April 10, 1993
When CLK calculates a new adjustment value, it
tries to determine if any of the M= values are out
of line with the rest of the values. It will
ignore, but provide an error message, if any of
the values are too far away from all of the oth-
ers. CLK calculates an average and standard devi-
ation and ignores all values (of adjustment per
day) that are more than 2 standard deviations from
the average.
R=A
The R= function sets restrictions on time changes.
R=A inhibits All time changes. When this mode is
set, all attempts to change the time are ignored
by CLOCK.SYS. This includes time changes attemp-
ted by CLK including time adjustments. See R=N.
R=B-hh:mm:ss
This function limits the amount of Backward change
of the time. Any change of more than the speci-
fied time is ignored. The "-" is optional as are
the offset fields.
clk r=b
inhibits all backward changes.
CLK R=B::2
only allows backward changes of two seconds or
less This might permit CLK to perform adjustments
but effectively stop other backward changes.
R=F+hh:mm:ss
This function limits the amount of Forward change
of the time. Any change of more than the speci-
fied time is ignored. The "+" is optional as are
the offset fields.
CLK R=F+1:00:02
limits forward changes to 1 hour and 2 seconds.
The R=B and R=F limits do not apply to the auto-
matic conversions between standard and daylight
savings time as these don't actually change the
time. The R=B and R=F functions are also indepen-
dent of the R=A function.
R=N
This function reverses the R=A function and inhib-
its No clock changes. The R=A is independent of
the R=B and R=F. You can set backward and forward
limits with R=B and R=F. Later you can inhibit
18
CLOCK Version 3.47 April 10, 1993
all changes with R=A. When you do R=N, the previ-
ously set R=B and R=F limits again have an effect.
R=R
This function Resets the limits established by R=B
and R=F. No limits are in effect after executing
this function. It has no effect on the R=A mode.
S=C
Sets both clocks to the current time from the
calendar clock. You can use this even if the
clocks are disconnected to make the DOS clock
equal to the calendar clock. The time zone offset
is set to 00:00:00 and the time zone name is set
to UTC to indicate that both clocks are set to the
base time.
S=D
Sets both clocks to the current time from the DOS
clock. The value from the DOS clock is written to
the calendar clock. The time zone offset is set
to 00:00:00 and the zone name is not changed to
indicate that both clocks are set to your local
time.
TZ=...
Sets the DOS clock to the correct local time based
on the value of the expression following the TZ=.
This expression conforms exactly to the POSIX
1003.1 standard for time zone handling. CLK as-
sumes that the calendar clock currently contains
UTC (also known as GMT, Greenwich, ZULU, and Z
time). UTC ("Universal Time, Coordinated" is
usually spoken as "coordinated universal time") is
the name of the international standard time that
is provided by WWV, WWVH, the Naval Observatory,
and NIST as well as many other services around the
world. Most Unix(r) systems also support TZ
although many only partially support the POSIX
standard. See the notes later for a complete
description of the TZ= function.
You can put the CLK TZ=... command in your
AUTOEXEC.BAT file. You should put it prior to any
other statements that may create or update files
____________________
Unix is a registered trademark of Unix Systems Laboratories.
19
CLOCK Version 3.47 April 10, 1993
or you run the risk of having confusing times in
your file directory (MAKE could get especially
confused.). If you provide a TZ= function, your
system will automatically adjust to the correct
time zone every time you boot. Note that no at-
tempt is made to change between daylight and stan-
dard time except when you execute CLK TZ=...
Adjusting on the fly is very dangerous. Many pro-
grams can produce incorrect results or even cor-
rupt your data if time takes a big step forward
and are even more likely to do so if time runs
backward. See section 2.2 for a discussion of the
TZ= format.
NOTE: If you use the TZ= function and also use
WINDOWS, you will need to modify your SYSTEM.INI
file. The SYSTEM.INI file is found in your WIN-
DOWS directory. WINDOWS performs a function very
similar to the C=R function, but WINDOWS uses the
BIOS to go directly to the hardware clock and
hence bypasses CLOCK.SYS. The result will usually
be your time changing everytime you enter WINDOWS.
Fortunately you can avoid that by editing the
SYSTEM.INI file. In the SYSTEM.INI file, find the
line that looks like:
[386Enh]
Immediately after that line or anywhere in the
[386Enh] section, insert a line that looks like:
SyncTime=false.
W=-back,+forward
The W= function is used to establish Warning lim-
its on the time. Each time the W= function is
processed (usually from the CLK.INI file), the
current time and the previous time are compared.
If the current time is outside the -back,+forward
range around the previous time, a warning message
is displayed requiring you to press a key. The
program will also exit with an ERRORLEVEL of 1.
The full form of the W= function is:
W=N-days/hh:mm:ss,+days/hh:mm:ss,
YYYY-MM-DD,hh:mm:ss
The days sub-field is a value from 0 to 250 days.
The days sub-field combined with the time sub-
fields gives the maximum interval around the pre-
vious time within which the current time must
20
CLOCK Version 3.47 April 10, 1993
fall. The previous date and time follow the sec-
ond comma. For example,
clk w=-0/00:00:02,+91
will establish a range of minus two seconds to
plus 91 days. The first time you use this func-
tion nothing will happen except that CLK will add
the current date and time to the command and store
it in the CLK.INI file. The next time you use if
from the CLK.INI file with CLK /I, the current
date and time will be compared to the previous
date and time and the range. If the current time
is outside the range, a message is displayed and
CLK pauses.
The sign characters and all of the sub-fields are
optional. Missing sub-fields are treated as zero.
The particular separators are not important except
for the commas. Any non-digit character can be
used for the other separators. The time and date
fields are appended to the function by CLK when
the CLK.INI file is written and are the previous
time to which the next comparison will be made. A
typical function might be W=,31. This command
will display a warning whenever time has moved
backwards at all or has moved forwards by more
than 31 days since the last time you used CLK /I.
If you use CLK /I (see below) in your AUTOEXEC.BAT
file, this is very likely to detect a miss-set
clock or bad clock battery. Yet it won't generate
a message on every boot. You will only get an
"unnecessary" message if it has been more than a
month since you last used the PC.
If the "N" character (or "n") appears immediately
after the "=", CLK does not pause and wait for you
to press a key after printing the warning message.
The "N" allows you to use CLK in a .BAT file and
check for the warning with the IF ERRORLEVEL com-
mand.
/B
The B option tells CLK to remain in command mode
even if no other functions or options are present.
The /B in itself performs no operation, but it
avoids CLK going into full-screen mode if all you
want to do is display the current status (e.g., in
a .BAT file).
21
CLOCK Version 3.47 April 10, 1993
/I[,C]
or
/Ifile[,C]
The I option tells CLK to read the CLK.INI file
(or "file" if that is given) for additional func-
tions. These functions are usually A=, L=, and W=
functions that were previously written to the file
by CLK. You may add any other functions (but no
options) to the file and they will be processed as
if you had entered them at the end of the command
line. If you don't specify "file" or you don't
give a path as part of "file", CLK will use the
directory which contains CLK.EXE. Thus the de-
fault is to use CLK.INI in the directory that
contains CLK.EXE.
If you enter an A=, L=, M=, or W= function or CLK
finds them in the file, the file will be updated
with the new values for the current time when
appropriate. If an adjustment is made, the L=
function will reflect the date and time of the
latest adjustment. CLK will update or create a
CLK.INI file even if you don't use the /I option
if you use the A=, L=, M=, or W= functions on the
command line.
It is very useful to store your standard TZ=, C=,
and R= functions in the CLK.INI file. Then your
AUTOEXEC.BAT file can simply contain a CLK /I
command to set your clocks into their standard
modes, adjust the time, and check for bad clock
values. You can also reestablish your standard
modes after changes with the same command entered
from the DOS prompt or a .BAT file.
The file may be hidden and still be updated with-
out error. However, to update a read-only file,
you must add ,C to the end of the option. This
indicates that CLK may Change the attributes of
the file in order to update it. CLK will restore
the original attributes. System files may not be
updated.
/M[,C]
or
/Mfile[,C]
The M option is identical to the I option except
that only the M= function lines are read from the
22
CLOCK Version 3.47 April 10, 1993
file. Its primary use is internal to CLK when
processing an M= function from the command line.
You may also use /Mfile to specify the location of
the file when entering M= values. You may also
use the M option to cause recalculation of the
adjustment factor at any time (e.g., after editing
the file).
/P
or
/PN
Controls the use of password protection of mode
changes. When you use /P, CLK will ask you for a
new password. It will then ask you to repeat the
password to ensure that you entered what you want.
It does not display the password as you enter it.
The password is then passed to CLOCK.SYS and pass-
word protection is enabled. On future calls to
CLOCK.SYS, you will be asked for the password if
protection is enabled. You may use /PN to disable
password protection, but you will have to provide
the current password to do so. If used with the
/S feature, the password protection will remain in
effect even across reboots. /P should be the last
field on a CLK command line.
/S
or
/Sfile
Saves the current copy of CLOCK.SYS as it resides
in memory. If you do not specify the file, the
memory version is written to file CLOCK.NEW in the
same directory that contains CLK.EXE. While you
may directly overwrite the file CLOCK.SYS, you
should be very careful doing so as whatever your
current state is will take effect on the next
boot.
PLEASE MAKE A BACKUP COPY of your original
CLOCK.SYS before replacing it with a saved file.
The saved file does not do any probing at boot
time as it already knows exactly what your clock
is. It does not need any parameters on the de-
vice= line in CONFIG.SYS.
The /S option may be extremely useful for anyone
with multiple similar systems to maintain. You
can set up all of your options once on one ma-
23
CLOCK Version 3.47 April 10, 1993
chine, save those with the /S option, and then use
the saved file to directly install on all the
other machines. If you use password protection,
no one can change the other systems except by
modifying CONFIG.SYS to remove the loading of
CLOCK.SYS.
You will still need to run CLK as part of every
boot operation (e.g., in AUTOEXEC.BAT) to do any
automatic adjustment (A= and L= functions), check
for clock failures (W= function), and check to see
whether the clock should use the standard or day-
light offsets (TZ= function). These functions are
not processed automatically by CLOCK.SYS because
they would increase the size of the device driver
to an unacceptable limit.
/?
"/?" or any error will cause CLK to display the
usage format. If you have an error in any field,
CLK first displays that field.
TZ=:?
"TZ=:?" or any error in a TZ= function that refers
to a pre-defined time zone causes CLK to display
all the current pre-defined time zone names and
their associated values.
2.2 Format of TZ= Function
The format of TZ=... can get quite complicated as the standard is
trying to deal with all time zones and daylight savings time
rules around the world. The full format is:
TZ=:zone
or
TZ=STD[offset][DAY[offset][,start[/time],end[/time]]]
Parameters zone
The form TZ=:zone is the one you are most likely
to need. CLK knows the offsets and daylight sav-
ings time rules for most of the U.S. and all you
have to supply is the name of your time zone. The
time zones currently known to CLK are:
EST Eastern U.S. with automatic daylight
CST Central U.S. with automatic daylight
MST Mountain U.S. with automatic daylight
24
CLOCK Version 3.47 April 10, 1993
PST Pacific U.S. with automatic daylight
HST Hawaiian with no daylight savings time
MET Mediterranean with automatic daylight
You can use CLK TZ=:? to display the list of pre-
defined zone names and their values.
If you would like your favorite time added, please
send me the names, offset from UTC, and any day-
light savings time rules that are different from
the U.S. NOTE: The names can be composed of any
characters except digits, plus, minus, and comma.
They can be up to 32 characters long. Case is
preserved in the names only for later display by
CLK. You can call your zone MyZone.
Case is not important in matching the zone names.
tz=:cst is the equivalent of TZ=:CST. Both will
find the definition of CST.
You don't have to wait for me to modify CLK in order to
use your local rules or just try something out. That's
what the long form is for.
STD
is any time zone name for standard time that you
want to use. See the note above for the rules.
offset
is the difference between your local time and UTC
and is expressed as hh[:mm[:ss]] with an optional
leading + or -. Offsets for times West of Green-
wich are positive and those East are negative. A
24-hour clock is used with times running from
00:00:00 to 23:59:59. Mountain Standard time
would be expressed as:
TZ=MST+07:00:00
or
TZ=MST7
and that's what you would use if you live in Ari-
zona and don't want any daylight savings time
adjustments.
25
CLOCK Version 3.47 April 10, 1993
DAY
is the time zone name for daylight savings time.
If you don't use daylight savings time in your
location, you should not supply this or any of the
following fields.
The offset for daylight time is in the same form
as for standard time. If you don't give this
offset, it is assumed to be one hour later than
standard time. Thus a more complete specification
of the Eastern time zone would be:
TZ=EST+05:00:00EDT+04:00:00
or
TZ=EST5EDT4
or
TZ=EST5EDT (since daylight is one hour
later by default)
start
is the day of the year on which daylight savings
time starts. There are three formats that you can
use to give this day. They are given below.
end
is the day of the year on which standard time
starts again. Note that in the Southern hemi-
sphere it is quite possible for "end" to be earli-
er in the year than "start" as daylight savings
time will include December and January. end is in
the same format as start. Note from the syntax
above that you must provide end if you provide
start.
time
is the time of day that the change takes place.
It is in exactly the same format as offset except
that leading + and - signs are not allowed. If
you do not specify the time, 02:00:00 is used as
the default.
The day of the year form for start and end may be any of:
Jn
where n is a Julian day of the year from 1 to 365.
This form does not allow you to refer to February
29. Day 59 is always February 28 and Day 60 is
always March 1. This is most useful in locations
26
CLOCK Version 3.47 April 10, 1993
where a particular calendar date is used every
year.
n
where n is a Julian day of the year from 0 to 365.
This form does allow you to refer to February 29.
January 1 is day 0, February 28 is day 58, and
either February 29 or March 1 is day 59 depending
on whether it is a leap year or not. Not the most
useful of forms but it does deal with locations
that might specify February 29 as the date that
time changes.
Mm.w.d
is used in places like the U.S. that do not speci-
fy a date, but rather specify a rule. m is the
month (1 to 12). d is the day of the week
(0=Sunday, 1=Monday, ... 6=Saturday). w is the
week of the month (1 to 5). Week 1 indicates the
first time that day d occurs in that month. Week
5 indicates the last time that day d occurs in
that month whether it is the 4th or 5th time.
Thus the U.S. rule is
M4.1.0/02:00:00,M10.5.0/02:00:00
or the first Sunday in April at 2AM until the last
Sunday in October at 2AM.
The long form for Central U.S. time is:
TZ=CST+06:00:00CDT+05:00:00,M4.1.0/02:00:00,M10.5.0/02:00:00
or
TZ=CST6CDT5,M4.1.0/2,M10.5.0/2 (just leaving out zeros)
or
TZ=CST6CDT,M4.1.0,M10.5.0 (since 2AM is default)
or
TZ=CST6CDT (since the U.S. rule is
the default)
2.3 Using CLK
The most common use of CLK will be to handle your time zone and
daylight savings time changes. You need only do the following:
1. Set your clocks to UTC.
2. Include the following line in your AUTOEXEC.BAT file.
27
CLOCK Version 3.47 April 10, 1993
CLK TZ=:zone (where you use one of the pre-defined
zones)
or
CLK TZ=... (where you define your own rules)
That's it. Everything else will take care of itself.
The only other time you will need to do anything is if you decide
to correct your calendar clock to a more accurate time. You will
probably use TIMESET or one of the other programs that call the
Naval Observatory or NIST or maybe just your watch that you have
set accurately.
If you don't want to have to change the configuration of the time
setting program, you may want to have it always set UTC or at
least your local standard time. If you want to have it set UTC
time, do the following:
CLK S=C C=W
run your time set program
CLK TZ=... (your normal TZ value)
The C=W in the first line is only required if you normally run
with the clocks disconnected.
Note that if you tell the time set program what your current time
zone is, you don't have to do anything unless you have the clocks
disconnected.
Notes Leaving your clock on local time ________________________________
If you don't want to be bothered with UTC, CLK will
quite happily work with your calendar clock set to its
current value. For example, let's assume that you
currently have both clocks set to Pacific Standard Time
and you don't really want to be bothered changing to
UTC, but you would like future changes between standard
and daylight time to be handled automatically. Just
use the following statement in AUTOEXEC.BAT:
CLK TZ=PST0PDT
CLK believes whatever you tell it and will quite happi-
ly operate assuming that PST is equal to UTC. You
could even use CLK with your calendar clock set to
Pacific Daylight Time by using:
CLK TZ=PST1PDT
Avoiding missed days when your PC stays on all night,
and missed years and leap days on type 4 and 6 clocks _____________________________________________________
28
CLOCK Version 3.47 April 10, 1993
If your PC is often left on over midnight and seems to
miss the change to a new day, use:
CLK C=R TZ=...
in your AUTOEXEC.BAT file to have CLOCK.SYS periodical-
ly read the time and date from the calendar clock. If
your clock is a type 4 or 6 clock that doesn't update
years automatically and doesn't handle leap days, then
this setting also ensures that leaving your PC on over
the end of a year or across February 29 doesn't cause
you to get the wrong date.
Using CLK.INI to simplify your commands _______________________________________
If you always use the same functions, you may want to
edit the CLK.INI file that is included in this release.
You can include your TZ=, C=, and R= functions in the
file and just use:
CLK /I
in your AUTOEXEC.BAT file.
Adding and subtracting time ___________________________
You can pretty much do anything including simple arith-
metic on your clocks by using the functions in the
correct sequence. Let's say that you want to add 12
hours to the current time in both clocks because you
inadvertently set AM time instead of PM time. The
following function sequence will do that:
CLK TZ=Igoofed-12 S=D TZ=:pst
The TZ=Igoofed-12 (or use any other name for the zone)
sets your DOS clock to 12 hours later than the calendar
clock. (Yes, I know that time zone offsets seem back-
wards since you subtract them from the base time, but
that's the way the official standards have them.)
The S=D sets both clocks to the value in the DOS clock
with a zero offset.
The TZ=:pst should be replaced by whatever your normal
TZ function is or even by a /I to pull in your normal
settings.
If you normally have your clocks disconnected, insert a
C=W function as the first function.
Correcting inadvertent problems _______________________________
Just remember that except for the S=D function, CLK and
CLOCK.SYS always start with the assumption that the
calendar clock is the base and do all their calcula-
29
CLOCK Version 3.47 April 10, 1993
tions from that point. Thus you can play with TZ and
other functions as much as you want and always get back
to your normal local time just by using your normal TZ
command. The calendar clock will not have been affect-
ed unless you did something to set the time or date.
You can avoid even that problem by disconnecting your
clocks (C=D) or restricting time changes (R=A). In
fact, if you have trouble with some program messing up
your clocks, try the following:
CLK C=D
execute program
CLK S=C C=W (or C=R) TZ=... (your normal)
If you have your standard C= and TZ= functions in a
file, you can simplify this as:
CLK C=D
execute program
CLK S=C /I
You may even want to make up batch files containing
this sequence to run those troublesome programs. Some
games are major causes of problems because they set the
DOS clock running faster or slower than normal to
control the pace of the game. As long as they restore
the normal rate when they exit, the above sequence will
eliminate any clock drift problems.
Fast DOS clock drift ____________________
Some high-speed communication programs will also cause
the DOS clock to run slow by causing the BIOS to miss
clock interrupts. Fortunately, a C=R function should
virtually eliminate problems of this type.
2.4 Examples
clk A=0.34
sets an adjustment factor of 0.34 seconds per day. The
A=0.34 function will be written to the CLK.INI file
along with an L= function with the current time and a
zero remaining adjustment. Every time thereafter, that
CLK is run with the /I option, it will check to see if
it is time to adjust the clocks. About every third
day, it will add 1 second to both clocks.
clk s=c /i
30
CLOCK Version 3.47 April 10, 1993
sets the DOS clock to the current calendar clock time
without any time zone adjustment. The /i causes all
functions in the CLK.INI file to be added. If one of
them is a tz function, we have corrected the DOS clock
for any changes made to it and re-established our time
zone. This is a good command line to use following a
clk c=d
and other operations that may have led to an incorrect
time in the DOS clock.
clk c=r tz=:est r=b-00:00:02 r=f+00:00:02
sets CLOCK.SYS to read the calendar clock about every
10 seconds and re-synchronize the DOS clock with it;
applies the appropriate Eastern time zone (standard or
daylight depending on date); and prohibits changes to
the clock of more than 2 seconds in either direction.
2.5 Errors
When errors are detected, CLK prints a message. It also sets the
ERRORLEVEL on each program termination as follows:
0 Normal termination or only warning messages.
1 Time outside warning range. Warning issued.
2 Error in command line or CLK.INI file functions. The func-
tion with the error is displayed followed by the appropriate
usage rules.
3 Internal error or system error (e.g., unable to open handle
to CLOCK.SYS).
2.6 Future Enhancements
Several enhancements are planned for future releases of CLK.
- Full screen interface that displays the current status
of all the things that CLK and CLOCK.SYS know and lets
you change them just by editing the screen. The rather
clunky command line interface needs to remain as its
compact function definitions are what you want in a
.BAT file.
31
CLOCK Version 3.47 April 10, 1993
- Direct dialing of the Naval Observatory or NIST to get
the correct time with automatic creation of M= func-
tions from the results.
32
CLOCK Version 3.47 April 10, 1993
3 CLKDEMO.EXE
A simple version of the CLK program, called CLKDEMO, is provided
in both executable and source code form. CLKDEMO only provides
support for the C= functions and displaying the clock status. It
is included to show you how to add clock handling to your own
applications. CLKDEMO is written in C and is compiled with
Microsoft C 5.1.
3.1 CLKDEMO Command Line
Syntax CLKDEMO [C=A|D|R|W] [/?]
The functions provided work exactly as they do in CLK. CLKDEMO
also displays the status and the current times.
Since CLKDEMO.EXE is merely a subset of CLK.EXE, it isn't terri-
bly useful as a utility in its own right. Its value is that the
source code is provided. There are three source code files
provided. CLKDEMO.C is the main program and performs command
interpretation and execution. IOCTL.C is a set of functions that
read and write the CLOCK$ device driver using the DOS IOCTL
functions. IOCTL.H is a set of definitions which are used by
CLKDEMO and IOCTL.C. CLKTYP.H is a list of the clock types
currently supported by these programs. It is used to display the
type.
33
CLOCK Version 3.47 April 10, 1993
4 IOCTL - API TO CLOCK.SYS
IOCTL is provided to allow you to build your own applications to
use the additional functions that CLOCK.SYS provides. There are
several APIs (Application Programming Interfaces) provided as
part of IOCTL. These APIs are sufficient to perform all of the
extended functions.
All of the APIs are defined to be directly callable from all
Microsoft compatible languages including MASM, FORTRAN, Pascal,
and BASIC. Languages other than C refer to the API names as
upper case characters. Object code versions are provided for the
small, medium, and large memory models. These may be linked
directly with your applications. The object code versions are
SIOCTL.OBJ, MIOCTL.OBJ, and LIOCTL.OBJ for the small, medium, and
large models respectively.
4.1 Data Structures
Data structures are defined in ioctl.h that are used in the calls
to the IOCTL functions.
/* "modes" holds flags that control the operation of CLOCK.SYS */
struct modes {
unsigned : 9;
unsigned day_light: 1;
unsigned disp_24 : 1;
unsigned disp_tim : 1;
unsigned pw_ena : 1;
unsigned disabl : 1;
unsigned chk_forw : 1;
unsigned chk_back : 1;
};
/* "off" holds a time offset in hours, minutes, and seconds. */
struct off {
int hour;
int minute;
int second;
};
34
CLOCK Version 3.47 April 10, 1993
/* "date_time" is a structure that holds a date and time. */
struct date_time {
int year;
int month;
int day;
struct off time;
int hsecond;
};
/* "time_zone" holds a time zone name and offset. */
struct time_zone {
struct off offs;
unsigned char zone[32];
};
/* "limit" is used to hold the data that sets time limits for
changes. */
struct limit {
struct off back;
struct off forward;
};
/* "disp" is used to hold the data that specifies the location
and attributes of the continuous time display. */
struct disp {
int x;
int y;
int attribute;
};
35
CLOCK Version 3.47 April 10, 1993
/* CLOCK_DATA is the CLOCK.SYS data that is returned by clksta
(AKA CLKSTA for FORTRAN, Pascal, and BASIC languages). Because
we need to be language independent, all of the data is word-
aligned. Only the data types int and character are used. Some
of the int data is encoded bits or addresses. */
struct CLOCK_DATA {
int connected; /* Connection state */
struct modes mode; /* Mode bits */
struct date_time cal_time; /* Current date and time */
struct time_zone standard; /* Offset of standard UTC */
struct time_zone daylight; /* Daylight offset */
struct limit rules; /* Maximum clock movement */
struct disp display; /* Time display loc and attr */
unsigned char vers[6]; /* CLOCK.SYS version nnn.nn */
int clock_type; /* Type of clock installed */
int ct_1; /* Data for clock type */
int ct_2;
int ct_3;
int ct_4;
unsigned int clock_seg; /* Segment CLOCK.SYS loaded at*/
unsigned int clock_long; /* Size of CLOCK.SYS */
};
This data structure is treated as the following integer array in
the FORTRAN and BASIC languages.
BASIC _____
OPTION BASE 1
DIM CDATA(66)
FORTRAN _______
INTEGER*2 CDATA(66)
ARRAY INDEX CONTENTS STRUCTURE ELEMENT ___________ ________ _________________
CDATA(1) = Connection state connected
CDATA(2) = Mode bits mode
CDATA(3) = Year from calendar clock cal_time.year
CDATA(4) = Month cal_time.month
CDATA(5) = Day cal_time.day
CDATA(6) = Hour cal_time.offs.hour
CDATA(7) = Minute cal_time.offs.minute
CDATA(8) = Second cal_time.offs.second
CDATA(9) = 100th of second cal_time.hsecond
CDATA(10) = Standard hours from UTC standard.offs.hour
CDATA(11) = Standard minutes standard.offs.minute
CDATA(12) = Standard seconds standard.offs.second
36
CLOCK Version 3.47 April 10, 1993
CDATA(13) - standard.zone
CDATA(28) = Standard time zone LJSF
CDATA(29) = Daylight hours from UTC daylight.offs.hour
CDATA(30) = Daylight minutes daylight.offs.minute
CDATA(31) = Daylight seconds daylight.offs.second
CDATA(32) - daylight.zone
CDATA(47) = Daylight time zone LJSF
CDATA(48) = Maximum hours backward rules.back.hour
CDATA(49) = Maximum minutes backward rules.back.minute
CDATA(50) = Maximum seconds backward rules.back.second
CDATA(51) = Maximum hours forward rules.forward.hour
CDATA(52) = Maximum minutes forward rules.forward.minute
CDATA(53) = Maximum seconds forward rules.forward.second
CDATA(54) = x cursor position display.x
CDATA(55) = y cursor position display.y
CDATA(56) = attribute display.attribute
CDATA(57) - vers
CDATA(59) = CLOCK.SYS version LJSF
CDATA(60) = Clock type clock_type
CDATA(61) = I/O address, base memory ct_1
segment, or base year
CDATA(62) = Read memory offset ct_2
CDATA(63) = Write-0 memory offset ct_3
CDATA(64) = Write-1 memory offset ct_4
CDATA(65) = Segment address clock_seg
where CLOCK.SYS is loaded
CDATA(66) = Length of CLOCK.SYS clock_long
4.2 clksta
■ Summary
C _
#include <ioctl.h>
extern int pascal far clksta(struct CLOCK_DATA *cdata);
BASIC _____
OPTION BASE 1
DIM CDATA(66)
DECLARE FUNCTION CLKSTA%(BYVAL Addr AS INTEGER)
STATUS% = CLKSTA(VARPTR(CDATA(1)))
37
CLOCK Version 3.47 April 10, 1993
FORTRAN _______
INTEGER*2 CDATA(66)
INTEGER*2 STATUS
INTEGER*2 CLKSTA
STATUS = CLKSTA(CDATA)
■ Description
clksta returns all of the information about CLOCK.SYS in a
structure. In FORTRAN and BASIC the structure appears to be an
integer array. The above structure declarations can be approxi-
mated in Pascal. For a description of the values of each ele-
ment, see the individual APIs below. The elements not described
as part of the input to other functions are:
unsigned char vers[6]; /* CLOCK.SYS version nnn.nn */
int clock_type; /* Type of clock installed */
int ct_1; /* Data for clock type */
int ct_2;
int ct_3;
int ct_4;
unsigned int clock_seg; /* Segment CLOCK.SYS loaded at */
unsigned int clock_long; /* Size of CLOCK.SYS */
CDATA(57) -
CDATA(59) = CLOCK.SYS version LJSF characters
CDATA(60) = Clock type (see type numbers in appendix B)
CDATA(61) = I/O address, base memory segment, or base
year
CDATA(62) = Read memory offset
CDATA(63) = Write-0 memory offset
CDATA(64) = Write-1 memory offset
CDATA(65) = Segment address at which CLOCK.SYS is loaded
CDATA(66) = Length in bytes of CLOCK.SYS
vers or CDATA(57) - CDATA(59)
Is the version number of the CLOCK.SYS that is in-
stalled. This is returned as a 6-character, left-
justified, space-filled (LJSF) character string. For
example, "3.49 ".
clock_type or CDATA(60)
Is the type number of the clock being used. See Appen-
dix B for the type numbers.
38
CLOCK Version 3.47 April 10, 1993
ct_1 or CDATA(61)
Is the value of the first clock parameter. This is the
base I/O address for I/O bus clocks, the base memory
segment address for memory-mapped clocks, or the base
year for the AT&T clocks.
ct_2 or CDATA(62)
Is the read offset for memory-mapped clocks.
ct_3 or CDATA(63)
Is the write 0-bits offset for memory-mapped clocks.
ct_4 or CDATA(64)
Is the write 1-bits offset for memory-mapped clocks.
clock_seg or CDATA(65)
Is the segment address at which CLOCK.SYS is loaded.
CLOCK.SYS always starts at offset zero in this segment.
clock_long or CDATA(66)
Is the length of CLOCK.SYS in bytes.
■ Arguments cdata
is a pointer to a location to place the
current state information from
CLOCK.SYS.
■ Return Value
If clksta is successful, the function returns 0. Otherwise, it
returns a non-zero value and _doserrno is set to the correspond-
ing error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
39
CLOCK Version 3.47 April 10, 1993
4.3 setpw
■ Summary
C _
#include <ioctl.h>
extern void pascal far setpw(unsigned char *pw);
BASIC _____
DECLARE SUB SETPW(BYVAL S AS INTEGER)
A$ = "MyPasswd"
CALL SETPW(SADD(A$))
Note that A$ must be at least 8 characters long. Only the first
8 characters will be used.
FORTRAN _______
CHARACTER*8 PW
PW = "MyPasswd"
CALL SETPW(PW)
■ Description
The setpw function sets the password to be used on subsequent
calls to any of the following functions. These functions auto-
matically supply the most recent password when they call
CLOCK.SYS. You need not ever call setpw if you are not using
password protection. CLOCK.SYS will only check the password if
password protection is enabled through the stmode function.
■ Arguments pw
is a pointer to the password string.
This string should be exactly 8 charac-
ters long and must be at least 8 charac-
ters long. The password should also be
LJSF as every character is significant.
Case is significant in passwords.
40
CLOCK Version 3.47 April 10, 1993
■ Example
#include <ioctl.h>
main()
{
unsigned char pw[9] = "MyPasswd";
/* Set password to use on subsequent function calls. */
setpw(pw);
}
4.4 connec
■ Summary
C _
#include <ioctl.h>
extern int pascal far connec(int *conn);
BASIC _____
DECLARE FUNCTION CONNEC%(CONN AS INTEGER)
STATUS% = CONNEC(CONN)
FORTRAN _______
INTEGER*2 CONN, STATUS, CONNEC
STATUS = CONNEC(CONN)
■ Description
The connec function provides a means of setting the connection
state of CLOCK.SYS.
41
CLOCK Version 3.47 April 10, 1993
■ Arguments conn
specifies the new connection mode. The val-
ues are:
0 = disconnected (C=D)
1 = connected for writes only (C=W)
2 = connected for writes and periodic reads
(C=R)
3 = connected for all operations (C=A)
■ Return Value
If the return value is zero, the function succeeded. If the
return value is non-zero, an error has occurred and _doserrno is
set to the corresponding error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
■ Example
#include <stdio.h>
#include <ioctl.h>
main()
{
int conn_write = 1;
int status;
/* Set clock to connected for writes */
status = connec(&conn_write);
if (status)
printf("Error %X in connec\n", status);
}
42
CLOCK Version 3.47 April 10, 1993
4.5 newpw
■ Summary
C _
#include <ioctl.h>
extern int pascal far newpw(unsigned char *pw);
BASIC _____
DECLARE FUNCTION NEWPW%(BYVAL S AS INTEGER)
A$ = "MyPasswd"
STATUS% = NEWPW(SADD(A$))
Note that A$ must be at least 8 characters long. Only the first
8 characters will be used.
FORTRAN _______
CHARACTER*8 PW
INTEGER*2 STATUS, NEWPW
PW = "MyPasswd"
STATUS = NEWPW(PW)
■ Description
The newpw function sets a new password for CLOCK.SYS. This
function is not sufficient to enable password protection. You
must also use stmode to turn on password checking. BE SURE to
use newpw before you use stmode to turn on password checking. If
you turn on password checking without first setting the password
to something that you know, you will never be able to use the
CLOCK.SYS functions again until you reboot.
■ Arguments pw
is a pointer to the password string.
This string should be exactly 8 charac-
ters long and must be at least 8 charac-
ters long. The password should also be
LJSF as every character is significant.
Case is significant in passwords.
■ Return Value
43
CLOCK Version 3.47 April 10, 1993
If the return value is zero, the function succeeded. If the
return value is non-zero, an error has occurred and _doserrno is
set to the corresponding error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
■ Example
#include <stdio.h>
#include <ioctl.h>
main()
{
unsigned char pw[9] = "MyPasswd";
int status;
/* Set new password for CLOCK.SYS */
status = setpw(pw);
if (status)
printf("Error %X in setpw\n", status);
}
4.6 rstrct
44
CLOCK Version 3.47 April 10, 1993
■ Summary
C _
#include <ioctl.h>
extern int pascal far rstrct(int *bhour, int *bmin, int *bsec,
int *fhour, int *fmin, int *fsec);
BASIC _____
DECLARE FUNCTION RSTRCT%(BHOUR%, BMIN%, BSEC%, FHOUR%, FMIN%,
FSEC%)
FORTRAN _______
INTEGER*2 BHOUR, BMIN, BSEC, FHOUR, FMIN, FSEC
INTEGER*2 RSTRCT
STATUS = RSTRCT(BHOUR, BMIN, BSEC, FHOUR, FMIN, FSEC)
■ Description
The rstrct function sets backwards and forwards limits on time
changes. Any time changes that exceed these limits will be
ignored. For example, if a backward limit of 2 seconds is set,
no change that would move the clock backwards more than 2 seconds
will be processed. Setting the limits protects you agains keying
in a bad time and agains programs that may incorrectly set the
time. Yet you can still change the time within the prescribed
limits. For example, you may set a backward limit of 2 seconds
to permit CLK to adjust the time by up to 2 seconds while inhib-
iting any other backwards changes. These limits have no effect
on changing between standard and daylight times as that is not
really a change in the "time".
■ Arguments bhour:bmin:bsec
is the backward limit in hours, minutes
and seconds.
fhour:fmin:fsec
is the forward limit in hours, minutes,
and seconds.
■ Return Value
45
CLOCK Version 3.47 April 10, 1993
If the return value is zero, the function succeeded. If the
return value is non-zero, an error has occurred and _doserrno is
set to the corresponding error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
■ Example
#include <stdio.h>
#include <ioctl.h>
main()
{
int bhour = 0;
int bmin = 0;
int bsec = 2;
int fhour = 1;
int fmin = 0;
int fsec = 0;
int status;
/* Set time change limits to 2 seconds backwards and 1 hour
forwards */
status = rstrct(&bhour, &bmin, &bsec, &fhour, &fmin, &fsec);
if (status)
printf("Error %X in rstrct\n", status);
else
printf("Time limits set to "
"-%.2d:%.2d:%.2d,+%.2d:%.2d:%.2d\n",
bhour, bmin, bsec, fhour, fmin, fsec);
}
46
CLOCK Version 3.47 April 10, 1993
4.7 stmode
■ Summary
C _
#include <ioctl.h>
extern int pascal far stmode(struct modes *mode);
BASIC _____
DECLARE FUNCTION STMODE%(MODES%)
FORTRAN _______
INTEGER*2 MODES
INTEGER*2 STMODE
STATUS = STMODE(MODES)
■ Description
The stmode function sets a variety of operating modes. The
argument is actually a structure of bits. Each bit specifies
whether an operating mode is on (1) or off (0).
■ Arguments modes
is set of bits that specify operating
modes. The bit values are:
unsigned : 9; Unused
unsigned day_light: 1; 0x0200 (512)
unsigned disp_24 : 1; 0x0400 (1024)
unsigned disp_tim : 1; 0x0800 (2048)
unsigned pw_ena : 1; 0x1000 (4096)
unsigned disabl : 1; 0x2000 (8192)
unsigned chk_forw : 1; 0x4000 (16384)
unsigned chk_back : 1; 0x8000 (32768)
■ Return Value
If the return value is zero, the function succeeded. If the
return value is non-zero, an error has occurred and _doserrno is
set to the corresponding error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
47
CLOCK Version 3.47 April 10, 1993
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
■ Example
#include <ioctl.h>
main()
{
struct CLOCK_DATA cdata;
/* Set daylight savings time. */
clksta(&cdata); /* Get current mode settings. */
cdata.mode.day_light = 1; /* Turn on daylight */
stmode(&cdata.modes);
}
4.8 stzone
■ Summary
C _
#include <ioctl.h>
extern int pascal far stzone(int *shour, int *smin, int *ssec,
unsigned char sname[32], int *dhour, int *dmin,
int *dsec, unsigned char dname[32]);
48
CLOCK Version 3.47 April 10, 1993
BASIC _____
DECLARE FUNCTION STZONE%(SHOUR%, SMIN%, SSEC%, BYVAL SN AS
INTEGER, DHOUR%, DMIN%, DSEC%, BYVAL DN AS INTEGER)
SNAME$ = "32-CHARACTER STANDARD ZONE NAME "
DNAME$ = "Daylight savings time zone name "
STATUS% = STZONE(6,0,0,SADD(SNAME$),5,0,0,SADD(DNAME$))
FORTRAN _______
CHARACTER*32 SNAME, DNAME
INTEGER*2 STZONE, STATUS
SNAME = "CST"
DNAME = "CDT"
STATUS = STZONE(6, 0, 0, SNAME, 5, 0, 0, DNAME)
■ Description
The stzone function sets the standard time and daylight savings
time offsets from the calendar clock and the standard and day-
light time zone names or mnemonics. Note that the offsets are
subtracted from the calendar clock to get the local time. Thus
the standard time offset from UTC to EST is 5:0:0.
■ Arguments SHOUR:SMIN:SSEC
is the time difference between the cal-
endar clock and local standard time. It
may be a positive of negative value. If
negative, all three values must be nega-
tive.
SNAME
is the standard time zone name or mne-
monic. It must be a 32-character LJSF
character string. As with all other
character strings used by these func-
tions, there is no terminating NULL
character as is usual in C. The other
languages do not readily handle NULL
terminated strings. In C applications
you may define the character array to
contain 33 characters, but you must
ensure that the NULL character does not
occur in the first 32 characters.
49
CLOCK Version 3.47 April 10, 1993
DHOUR:DMIN:DSEC
is the time difference between the cal-
endar clock and local daylight savings
time. Whether the standard offset or
the daylight offset is currently used by
CLOCK.SYS is controlled by the setting
of the day_light mode bit (see stmode).
DNAME
is the daylight savings time zone name
or mnemonic. It must be a 32-character
LJSF character string.
■ Return Value
If the return value is zero, the function succeeded. If the
return value is non-zero, an error has occurred and _doserrno is
set to the corresponding error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
50
CLOCK Version 3.47 April 10, 1993
■ Example
#include <stdio.h>
#include <ioctl.h>
main()
{
unsigned char sname[33] = "PST ";
unsigned char dname[33] = "PDT ";
int shour = 8;
int smin = 0;
int ssec = 0;
int dhour = 7;
int dmin = 0;
int dsec = 0;
struct CLOCK_DATA cdata;
/* Get current status. */
clksta(&cdata);
/* Set time zone to U.S. Pacific time. */
stzone(&shour, &smin, &ssec, sname, &dhour, &dmin, &dsec,
dname);
/* Select daylight savings time. */
cdata.mode.day_light = 1;
stmode(&cdata.mode);
}
4.9 tdisp
■ Summary
C _
#include <ioctl.h>
extern int pascal far tdisp(int *dispx, int *dispy, int *attr);
51
CLOCK Version 3.47 April 10, 1993
BASIC _____
DECLARE FUNCTION TDISP%(DISPX%, DISPY%, ATTR%)
STATUS% = TDISP(72, 0, &H79)
FORTRAN _______
INTEGER*2 TDISP, STATUS
STATUS = TDISP(0, 72, 0x79)
■ Description
The tdisp function sets the coordinates and attribute for the
continuous time display. tdisp does not start or stop the
continuous display nor does it set the 12-hour or 24-hour mode.
Those are all provided by the stmode function.
■ Arguments DISPX
is the x (horizontal) cursor coordinate
for the continuous time display. The
rightmost character on a line is at x=0.
Be sure to leave enough space at the end
of the line to accommodate the entire 8-
chararacter time display. For example,
x=72 is the last position to specify on
an 80-character line.
DISPY
is the y (vertical) cursor coordinate
for the continuous time display. The
top line on the display is y=0.
ATTR
is the display attribute to use for the
continuous time display. ATTR is usual-
ly expressed as two hex digits. The
first (high-order) digit is the back-
ground color (0 to 7) and the second
digit is the text or foreground color (0
to F). For example, 0A would display
bright green letters on a black back-
ground. Background colors usually do
not include the bright colors. The
color numbers are:
52
CLOCK Version 3.47 April 10, 1993
0 Black
1 Blue
2 Green
3 Cyan
4 Red
5 Magenta
6 Brown
7 White
8 Grey
9 Bright blue
A Bright green
B Brigth cyan
C Bright red
D Bright magenta
E Yellow
F Bright White
■ Return Value
If the return value is zero, the function succeeded. If the
return value is non-zero, an error has occurred and _doserrno is
set to the corresponding error code. Possible values are:
0001h Invalid function. This should indicate that
CLOCK.SYS is not installed. It is the error that
the DOS clock device driver would return since it
doesn't handle these functions.
0005h Access denied. Indicates that DOS would not open
a handle for read access. You may not have enough
handles available.
0006h Invalid handle. Should not happen.
000Dh Invalid data. CLOCK.SYS reported a bad byte count
or otherwise did not process the request. This
should not happen.
53
CLOCK Version 3.47 April 10, 1993
■ Example
#include <stdio.h>
#include <ioctl.h>
main()
{
struct CLOCK_DATA cdata;
int dispx = 72;
int dispy = 0;
int attr = 0x79;
/* Get current CLOCK.SYS modes. */
clksta(&cdata);
/* Turn on 12-hour display at end of top line of screen.
Use bright blue text on a white backgroun. */
tdisp(&dispx, &dispy, &attr);
cdata.mode.disp_tim = 1;
cdata.mode.disp_24 = 0;
stmode(&cdata.mode);
}
54
CLOCK Version 3.47 April 10, 1993
5 CLOCK.SYS - ASSEMBLY LANGUAGE API
CLOCK.SYS has a couple of additional APIs (Application Program-
ming Interfaces) that are not present in the normal DOS CLOCK$
device driver. These interfaces are provided by the DOS IOCTL
(Input/Output of ConTroL data) functions. The Output Control
Data to Character Device function is used to set new operating
values for CLOCK.SYS for the C=, D=, R=, TZ=, and /P functions.
The Input Control Data from Character Device function is used to
get the current status and the date and time from the calendar
clock.
5.1 Opening the CLOCK$ Device
In order to use the additional APIs provided by CLOCK.SYS you
must open a handle to the CLOCK$ device driver. You do this
using the DOS INT 21H Open File with Handle (3DH) function
specifying read-write access. You then use the handle to invoke
the other functions. Sample assembly language is:
MOV AX,3D00H ; Open with read and write access
MOV DX,OFFSET filename ; Pointer to "CLOCK$" ASCIIZ string
; DS:DX must point to the string
INT 21H ; Call DOS function handler
; AX contains the handle on return if carry flag is not set.
5.2 Sending New Values to CLOCK.SYS
To change the state of CLOCK.SYS, you use the Send Control Data
to Character Device (4403H) DOS function. You send data to
specify the connection type, modes, time zone offsets and names,
restrictions, continuous display information, and password. You
may send any combination of these in any order. You must always
send the current password as the first 8 bytes. If password
checking is not enabled, it doesn't matter what the 8 bytes
contain, but you must still send the 8 bytes.
The data stream that you send to CLOCK.SYS consists of the
current password followed by a selection index, the data for that
selection, another selection index, its data, and so on.
55
CLOCK Version 3.47 April 10, 1993
The selection indices and the data stream associated with each
one are:
INDEX DATA ITEMS COMMENTS _____ __________ ________
1 connected two byte integer (0 : C=D, 1 : C=W,
2 : C=R, 3 : C=A)
2 mode two byte integer (see stmode for a de-
scription of the bits)
3 standard time_zone structure for standard time
daylight time_zone structure for daylight time
4 rules limits structure
5 display disp structure
6 password 8 bytes LJSF of new password
Sample assembly language to send new information to CLOCK.SYS:
curpw DB 8 dup(?) ; Current password
DW 1 ; Change connection
DW 2 ; to C=R
DW 4 ; Change limits
DW 0,0,2,1,0,0 ; to R=B-::2,F+1
DW 6 ; Set new password
DB "MyPasswd" ; to MyPasswd (case is important)
DW 2 ; Change modes
DW 0D000H ; to enable limits and password
; also sets standard time and
; no display
count equ $-curpw ; Length to send
...
MOV AX,4403H ; Send control data function
MOV BX,handle ; Value returned from open
MOV CX,count ; Value = number of bytes to send
MOV DX,OFFSET curpw ; Location of bytes to be sent
; DS:DX must point to the buffer
INT 21H ;
; OK if carry not set. CX will equal bytes actually taken.
56
CLOCK Version 3.47 April 10, 1993
5.3 Getting Current Status of CLOCK.SYS
To get the current status and time, you use the Receive Control
Data from Character Device (4402H) function. You can read all of
the CLOCK_DATA structure or any smaller amount of it that you
need, but you can only read starting at the beginning
Sample assembly language for reading the clock status is:
MOV AX,440CH ; Read control data function
MOV BX,handle ; Value returned from open
MOV CX,count ; Number of bytes to read
MOV DX,OFFSET buffer ; Location to store the data
; DS:DX must point to the buffer
INT 21H ; Call DOS
; Data returned if carry not set.
; CX will contain the actual number of bytes transferred.
57
CLOCK Version 3.47 April 10, 1993
APPENDIX A: DEFINITION OF SHAREWARE
Shareware distribution gives users a chance to try software
before buying it. If you try a Shareware program and continue
using it, you are expected to register. Individual programs
differ on details -- some request registration while others
require it, some specify a maximum trial period. With registra-
tion, you get anything from the simple right to continue using
the software to an updated program with printed manual.
Copyright laws apply to both Shareware and commercial software,
and the copyright holder retains all rights, with a few specific
exceptions as stated below. Shareware authors are accomplished
programmers, just like commercial authors, and the programs are
of comparable quality. (In both cases, there are good programs
and bad ones!) The main difference is in the method of distribu-
tion. The author specifically grants the right to copy and
distribute the software, either to all and sundry or to a specif-
ic group. For example, some authors require written permission
before a commercial disk vendor may copy their Shareware.
Shareware is a distribution method, not a type of software. You
should find software that suits your needs and pocketbook,
whether it's commercial or Shareware. The Shareware system makes
fitting your needs easier, because you can try before you buy.
And because the overhead is low, prices are low also. Shareware
has the ultimate money-back guarantee -- if you don't use the
product, you don't pay for it.
DISCLAIMER - AGREEMENT
Users of CLOCK must accept this disclaimer of warranty: "CLOCK
is supplied as is. The author disclaims all warranties, ex-
pressed or implied, including, without limitation, the warranties
of merchantability and of fitness for any purpose. The author
assumes no liability for damages, direct or consequential, which
may result from the use of CLOCK."
CLOCK is a "shareware program" and is provided at no charge to
the user for evaluation. Feel free to share it with your
friends, but please do not give it away altered or as part of
another system. The essence of "user-supported" software is to
provide personal computer users with quality software without
high prices, and yet to provide incentive for programmers to
continue to develop new products. If you find this program
useful and find that you are using CLOCK and continue to use
CLOCK after a reasonable trial period, you must make a registra-
tion payment of $10 to Ronald Q. Smith. The $10 registration fee
58
CLOCK Version 3.47 April 10, 1993
will license one copy for use on any one computer at any one
time. For a registration fee of $25, I will immediately send you
the latest version of CLOCK including the source code and this
document as a WordPerfect 5.1 file. You may use the source code
for your own maintenance of CLOCK or as a learning tool for any
software that you develop. You may not use all or part of the
source code in any software that you develop or release to others
without the permission of Ronald Q. Smith.
You must treat this software just like a book. An example is
that this software may be used by any number of people and may be
freely moved from one computer location to another, so long as
there is no possibility of it being used at one location while
it's being used at another. Just as a book cannot be read by two
different persons at the same time.
Commercial users of CLOCK must register and pay for their copies
of CLOCK within 30 days of first use or their license is with-
drawn. Site-License arrangements may be made by contacting
Ronald Q. Smith.
Anyone distributing CLOCK for any kind of remuneration must first
contact Ronald Q. Smith at the address below for authorization.
You are encouraged to pass a copy of CLOCK along to your friends
for evaluation. Please encourage them to register their copy if
they find that they can use it. All registered users will
receive a copy of the latest version of the CLOCK system.
Send the fees and any inquiries to:
Ronald Q. Smith
11 Black Oak Road
North Oaks, MN 55127-6204
You may also contact me via CompuServe mail at userid 71620,514.
I will be happy to respond to any problems and suggestions for
future capabilities.
You may register CLOCK through the CompuServe Shareware Registra-
tion program. CLOCK.SYS is found under registration ID 104. The
fee for registering through CompuServe is $12 (to cover their
charge) and will be added directly to your CompuServe bill.
59
CLOCK Version 3.47 April 10, 1993
APPENDIX B: CLOCK TYPES
B.1 Type 0 - PC/AT
IBM PC/AT and all fully compatible PCs. Most versions of DOS
fully support this clock interface without a separate driver.
Use CLOCK.SYS to provide support for CLK.EXE and CLKDEMO.EXE. If
you don't need the extra functions of CLK, you probably don't
need CLOCK.SYS. However, there were a couple of late 8088 PCs
that adopted the PC/AT clock standard but did not provide the
PC/AT recognition sentinel. DOS will not find the clock, but
CLOCK.SYS will.
Amstrad PC1521DD systems use this type of clock.
Automatic determination checks location F000:FFFE for the hex
value FC.
BIOS calls are used to read and write the clock values which are
usually stored in the CMOS RAM along with other configuration
information. The primary interfaces are:
Get Date: MOV AH,4
INT 1AH
Returns the year in CX and month and day in
DX in BCD format (e.g., a hex display would
show: CX=1991, DX=1009 for October 9, 1991).
Set Date: MOV AH,5
Load CX and DX as above for Get Date
INT 1AH
Get Time: MOV AH,2
INT 1AH
Returns hours and minutes in CX and seconds
in DH in BCD format. May also return 100ths
of seconds in DL (e.g., CX=2359, DX=5900 for
1 second before midnight).
Set Time: MOV AH,3
Load CX and DX as for Get Time
INT 1AH
60
CLOCK Version 3.47 April 10, 1993
B.2 Type 1 - Zenith Z-18x portables, Supersport 20
Automatic determination checks location F000:FFFA for the two-
byte hex value 4D32 ("M2").
BIOS calls are used to read and write the clock.
Get Date: MOV AH,2
INT 1AH
Returns CX=year (1980 - 2079) in binary and
DH=month, DL=day. All values are binary. A
hex display of the above date would look like
CX=7C7, DX=A09.
Set Date: MOV AH,3
Load CX and DX as for Get Date.
INT 1AH
Get Time: MOV AH,4
INT 1AH
Returns CH=hours, CL=minutes, DH=seconds. A
hex display would show: CX=173B, DX=3B00.
Set Time: MOV AH,5
Load CX and DX as for Get Time.
INT 1AH
B.3 Type 2 - Various Zenith Data System PCs.
Automatic determination looks at location F000:800A for the
pattern 00,F0,"ZDS".
Get Date: MOV AH,2AH
INT 1AH
Returns CX and DX as for type 1.
Set Date: MOV AH,2BH
Load CX and DX as for type 1.
INT 1AH
Get Time: MOV AH,2CH
INT 1AH
Returns CX and DX as for type 1.
Set Time: MOV AH,2DH
Load CX and DX as for type 1.
INT 1AH
61
CLOCK Version 3.47 April 10, 1993
B.4 Type 3 - Memory-Mapped Clocks
Memory-mapped clock used on some Zenith Data Systems PCs and
other similar clocks including many slot-less or no-slot clocks.
The SMT (Systems Manufacturing Technology) No-Slot clocks are
supported by this type.
Automatic determination is to attempt to read the clock. If
values other than all 0FFH or 0 are obtained, this clock type is
chosen. All known segments and offsets are tried.
Several different memory mapping approaches are used and many
different address possibilities are supported. In general a
segment address in the ROM region (C800H through FFFFH) is used.
Offsets from that segment address are used to read bits, write
zero bits, and write one bits. Documentation may specify those
segments and addresses in several forms. For example, segment
F000 with offset F002 is the same as segment FF00 with offset 2.
Each memory reference reads or writes a single bit. Read opera-
tions are used for all references with separate offsets for
reading a bit, writing a zero bit, and writing a one bit.
Clock segments and addresses currently probed include:
╔═══════╤═════════╤════════╤═════╤═════╤═════╤════════╗
║SEGMENT│WRITE 0 │WRITE 1 │READ │DECR │LAST │VENDOR ║
╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢
║F000 │ F002 │F003 │F004 │0000 │F000 │(Zenith)║
╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢
║FE00 │ 2 │ 3 │ 5 │0080 │C800 │SMT ║
╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢
║FE00 │ 0 │ 2 │ 8 │0080 │C800 │SMT ║
╚═══════╧═════════╧════════╧═════╧═════╧═════╧════════╝
Multiple address combinations may be tried for each clock pat-
tern. The DECR value is subtracted from the SEGMENT value for
another attempt at probing until the value equals LAST. Note
that like the SEGMENT address, DECR and LAST are in units of
paragraphs (16-bytes). Thus DECR of 80 is equivalent to 800H or
2048 bytes.
When the addresses used by a memory-mapped clock are determined
by probing, the segment and read address is displayed. As the
read address varies the most from one clock manufacturer to
another it is a good indication of the type of clock found.
62
CLOCK Version 3.47 April 10, 1993
Data is stored in BCD in bytes that you construct by shifting in
the bits. The most important data bytes are:
0 = Hundredths of seconds
1 = Seconds
2 = Minutes
3 = hours
5 = days
6 = months
7 = years mod 1980
B.5 Type 4 - Direct Register I/O Bus Clock
Many add-in clocks on expansion boards use this type of clock.
Some built-in clocks in PCs are also accessed similarly. This
clock was used on many AST Research I/O boards for 8088 PCs such
as the Six-Pack Plus, IO Plus, etc. Also used on some Tandy
systems (e.g., 1200HD) and the Vendex Turbo-888-XT.
Automatic determination is to attempt to read, complement, write,
re-read, and re-complement one of the registers. If the first
value read and the re-complemented second value are equal, the
register exists and is presumed to be the clock.
See also the description for types 6 and 7. If you aren't sure
which variant you have, specify type 8 and automatic probing will
determine if it is really a type 4, 6, or 7. For the greatest
chance of detecting the correct clock type, supply the base I/O
address if at all possible.
NOTE: If the clock is not correctly initialized (e.g., you have
just replaced the battery), CLOCK.SYS must initialize it so that
the counters will start working. CLOCK.SYS determines that the
clock has been previously initialized by looking at register 14H
(see B below). If register B contains the value 0DEH, the clock
is presumed to be initialized. If not, CLOCK.SYS will clear all
the registers to zero and start the counters running. While this
form of checking for initialization was commonly used, your
previous software may have used a different method. If so, the
first time you run CLOCK.SYS your date and time may be set to
zero (1980-1-1 00:00:00). If that happens, just enter the date
and time. It should work OK after that without resetting to zero
on further boots.
Each clock register is implemented as a separate I/O register ad-
dress. Clock base I/O addresses of 240H, 2C0H, 300H, and 340H
are supported by automatic probing. Similar clocks at other base
I/O addresses are supported by specifying type 4 and the base
63
CLOCK Version 3.47 April 10, 1993
address. The address range used is the base plus 0 through 1FH
(e.g., 2C0H through 2DFH).
Important registers are (using 2C0 as the example):
2C1 = 100ths of seconds
2C2 = seconds
2C3 = minutes
2C4 = hours
2C6 = days
2C7 = months
2C9 = month last time clock was read/set
2CA = years
2CB = initialized flag (0DEH if initialized)
2D4 = Status
All values are in BCD. That means that each register consists of
two 4-bit nybbles (a nybble is to a nibble as a byte is to a bite
- I haven't seen this used recently, but as a bit of trivia, the
first IBM 360 principles of operation manuals used that term and
that spelling - at least in a draft copy that we got in 1965).
Each nybble contains one decimal digit of the value. Years are
mod 1980 (i.e., 0 means 1980, 99 means 2079).
Since these clocks do not keep the year and do not handle leap
years for you, CLOCK.SYS does the necessary calculations to keep
the year correctly maintained and to adjust the date for leap
days. The clocks do provide a couple of memory locations in
which CLOCK.SYS maintains the year and previous month. As long
as you boot your system before a full year has passed, CLOCK.SYS
will correctly maintain the date.
B.6 Type 5 - Mitsubishi 8088 PCs
These were sold by Sperry as the PC-1 and PC/HT, by Leading Edge
as the Model D, by Mitsubishi, and others.
Automatic determination checks location F000:FFB3 for the string
"MITSUBISHI". Later Mitsubishi PCs which used a different clock
had the same string at a different location. We hope all early
versions had it at this location.
64
CLOCK Version 3.47 April 10, 1993
BIOS functions are used to access the clock.
Get Date: MOV AH,4
INT 1AH
Returns CL=year mod 1980, DH=month, and
DL=day all in binary. Also sets AL=0FFH if
the clock is busy and the request should be
retried.
Set Date: MOV AH,5
Load CL, DX as for Get Date.
INT 1AH
Returns AL=0FFH if busy.
Get Time: MOV AH,2
INT 1AH
Returns CH=hour, CL=minute, DH=second, and
AL=status. AL=0FFH means busy. AL=0 means
24-hour mode. AL=1 means AM and AL=3 means
PM.
Set Time: MOV AH,3
Load AL, CX, DH as for Get Time.
INT 1AH
Returns AL=0FFH if busy.
NOTE: Some early Mitsubishi PCs came with fixed disk controllers
that were not DOS compatible. In addition to the clock modifica-
tions, the DOS for those systems also handled the disk controller
variant. If you have such a PC, CLOCK.SYS is not sufficient to
enable you to go above DOS level 3.2. You will also need to
replace your fixed disk controller. I strongly suggest that you
create a boot floppy for your current DOS level before you try to
install your new DOS level. Then boot your new DOS from a floppy
disk, do SYS C: and copy COMMAND.COM to C:, then try a disk boot.
If the disk boot fails, boot the floppy you just created and do a
SYS C: and copy COMMAND.COM to C: to restore your old DOS ver-
sion. At that point, your best bet is to simply give up and stay
with DOS 3.2. If you want to proceed, you must replace your fixed
disk controller.
If SYS C: gives you an error status that indicates that there
isn't room for the new DOS version (very possible when moving
from 3.2 to 3.3 or above), you must backup your entire fixed disk
and use FORMAT C:/S to place the new version of DOS on the disk.
While this is a hassle, at least if your PC won't boot from the
disk, the fall-back approach is identical. There will be room to
put DOS 3.2 or earlier back on the fixed disk.
65
CLOCK Version 3.47 April 10, 1993
B.7 Type 6 - Indirect Register I/O Bus Clock
Used on AST Research boards and others. Typically uses the same
I/O base address as type 4. However the clock registers are
selected by sending the register address to the base I/O address
and then reading or writing data at the base I/O address + 1.
The internal register numbers and their contents are the same as
for type 4.
Automatic determination by probing the address register. If the
low-order bit is one, it may be this type of clock or type 7. We
then look further to determine if it is type 7. If you aren't
sure which type of clock you have but believe it is type 4, 6 or
7, specify type 8 and automatic probing will detect which variant
it is. If at all possible specify the base I/O address as that
will increase the likelihood that the correct determination is
made.
I/O addresses used are (again using 2C0 as the example base
address):
2C0 = Address register. Writing a value to this address
selects the internal register to read or write.
2C1 = Data register. Reading or writing this address,
reads or writes the internal register previously
selected by writing 2C0.
The internal register numbers are (the values to write to 2C0):
1 = 100ths of seconds
2 = seconds
3 = minutes
4 = hours
6 = days
7 = months
9 = month last time date was read or written
A = year
B = initialization flag
14 = status
Other processing is the same as type 4.
66
CLOCK Version 3.47 April 10, 1993
B.8 Type 7 - Complex I/O Bus Clock
Used on AST Research boards and others. Typically uses the same
base I/O address as types 4 and 6. Type 7 uses a more complex
register access sequence than type 6. Type 7 can be detected by
looking to see if the value in register D has bit 1 (value=2) set
which type 6 will not. If you aren't sure which type of clock
you have but believe it is type 4, 6 or 7, specify type 8 and
automatic probing will detect which variant it is. If at all
possible specify the base I/O address as that will increase the
likelihood that the correct determination is made.
The base I/O address is used as an address register and the base
+ 1 as a data register. This is the same as for clock type 6.
However, the internal registers and the form of the commands is
quite different. The primary difference is that the internal
registers only hold four bits of data each. Thus each internal
register represents a single decimal digit.
The I/O addresses are used as follows (using 2C0 as an example):
2C0 = Address register. The number of an internal reg-
ister plus 80H is written to this I/O address to
select an internal register.
2C1 = Data register. Four bits of data are read or
written using this I/O address from or to the
internal register previously selected by writing
to 2C0.
The internal registers are:
0 = Units digit of seconds
1 = Tens digit of seconds
2 = Units digit of minutes
3 = Tens digit of minutes
4 = Units digit of hours
5 = Tens digit of hours
6 = Day of week
7 = Units digit of day of month
8 = Tens digit of day of month
9 = Units digit of month
A = Tens digit of month
B = Units digit of year
C = Tens digit of year
D = Function register
E = Function register
F = Function register
67
CLOCK Version 3.47 April 10, 1993
B.9 Type 8 - Generic I/O Bus Clock
Type unknown. Probe only for types 4, 6, 7, 9, and B. Use type
8 if you are sure that you have an I/O bus clock (i.e., the clock
is on an add-in card) but aren't sure whether it is type 4, 6, 7,
9, or B. If at all possible, supply the base I/O address of the
clock as this will greatly increase the likelihood of the correct
handling method being chosen.
B.10 Type 9 - Quadram I/O Bus Clock
This type was used by Quadram Corporation on the QuadCard,
QuadCard II, and QuadCard 512+. It may have been used on others
as well.
Automatic determination checks to see that I/O registers exist at
310H or 210H.
This clock used four I/O control registers and twelve internal
registers. The I/O registers (using 310H as the example) are:
310 = Data register (used to move data values)
311 = Address register (used to select internal register)
312 = Function register (Read, write, hold counter)
313 = Control register (Enables read or write function)
68
CLOCK Version 3.47 April 10, 1993
The internal registers are:
0 = Units digit of seconds
1 = Tens digit of seconds
2 = Units digit of minutes
3 = Tens digit of minutes
4 = Units digit of hours
5 = Tens digit of hours - Also uses bit 2 (=4) to indicate
PM if in 12-hour mode and bit 3 (=8) to select 24-hour
mode
6 = Day of week (we don't use this)
7 = Units digit of days
8 = Tens digit of days - Also uses bit 3 (=8) to indicate
that this is a leap year. This bit must be set by
software whenever there is less than 366 days until the
next leap day. If you do not boot within that period,
leap day will not be taken.
9 = Units digit of months
10 = Tens digit of months
11 = Units digit of year mod 1980
12 = Tens digit of year mod 1980
NOTE: If you have this type of clock, you can only set the time
to the nearest minute. Whenever the time is set, the seconds are
always set to zero. You should set the time as the minute
changes. For that reason, you will not want to use the automatic
adjustment capability of CLK with this type of clock as it will
try to set the time to the nearest second.
B.11 Type A - AT&T 6300, 6300 PLUS, 6300 WGS
Automatic probing is accomplished by trying to read the clock.
If the read attempt using the BIOS is successful (carry flag not
set) and the values returned look like a valid time, the clock is
assumed to be present.
NOTE: AT&T clocks do not advance the year on January 1. It is
necessary to change the date at the beginning of each year.
Also, AT&T clocks always clear the seconds to zero when the time
is changed. For this reason you should always set the date and
time at the beginning of a minute. You should also not use the
automatic adjustment feature of CLK with these clocks.
A base year may be specified on the DEVICE= line. If it is not,
1992 will be used. This base will be good for all dates from
1992-1-1 till 1999-12-31.
69
CLOCK Version 3.47 April 10, 1993
BIOS functions are used with this clock.
Get Date: MOV AH,0FEH
INT 1AH
Returns BX = Days since base, CH = Hours, CL
= Minutes, DH = Seconds, DL = 100ths of sec-
onds
Set Date: MOV AH,0FFH
MOV BX,Days since base
MOV CH,Hours
MOV CL,Minutes
MOV DH,0
MOV DL,0
INT 1AH
B.12 Type B - Hyundai 8088 clock
Automatic determination probes the control registers. If they,
appear to be present, CLOCK tries to read the clock. Legal time
and date values will select this clock.
This clock uses I/O addresses E0H through EFH as follows:
E0 = Units digit of seconds
E1 = Tens digit of seconds
E2 = Units digit of minutes
E3 = Tens digit of minutes
E4 = Units digit of hours
E5 = Tens digit of hours
E6 = Day of week
E7 = Units digit of days
E8 = Tens digit of days
E9 = Units digit of month
EA = Tens digit of month
EB = Units digit of year
EC = Tens digit of year
ED = Control
EE = Control
EF = Control
70
CLOCK Version 3.47 April 10, 1993
APPENDIX C: REVISION HISTORY
930410 - Version 3.47: Add MET time zone to list of pre-defined
time zones (GMT-1). Document use of D= to resume last
display. Fix exit on TZ=:?. Add documentation about
modifying SYSTEM.INI when using TZ= in conjunction with
WINDOWS.
930403 - Version 3.46: Fix time of switch to daylight or stan-
dard. It was based on GMT and should have been based
on local time.
930311 - Version 3.45: Correct M= adjustment for the pending A=
adjustment.
930309 - Version 3.44: Modified M= to automatically set the date
and time on the L= to the same as the last M= if the L=
is earlier. It also sets any remaining adjustment to
zero. This is because the clock was adjusted exactly
at the point represented by the M=.
930306 - Version 3.43: Fixed bug with M= function not forcing a
read of the A= functions in CLK.INI and thus not cor-
rectly displaying the previous and new adjustment.
930304 - Version 3.42: Changed time moving backwards logic to
only look for earlier hours. At least one case has
been seen of a program that set the time backward a few
ticks by direct calls on the BIOS and resulted in
CLOCK.SYS advanceing the day. Now we only advance the
day if the time moves backwards an hour or more. Also
added the /N option for CLOCK.SYS that shuts off this
logic completely if the date advances unexpectedly.
Also fixed a bug in locating the CLK.INI file when the
A= function is used by itself.
930220 - Version 3.41: Changed timing window prevention logic in
CLOCK.SYS to control another possible case of the day
advancing twice over midnight.
930212 - Version 3.40: Added the M= function and /M option to
provide calculation of the adjmustment value. Added
help for all functions and options. Added the /B option
in anticipation of later support of full-screen mode.
Added the ,C flag on the /I and /M options to allow
updating a read-only file. Added error messages for
I/O errors when updating the file. Fixed timing window
in CLOCK.SYS that could occur when the continuous
71
CLOCK Version 3.47 April 10, 1993
display is operational that could cause the date to
advance unpredictably.
930204 - Version 3.31: Fixed bug in CLOCK.SYS with some clock
types causing system lockups or bad data to be re-
turned.
930130 - Version 3.30: Added support for a password and for
saving the current CLOCK.SYS state as a new copy of
CLOCK.SYS for future booting. Added continuous time
display. Changed API to support direct calls from
BASIC, FORTRAN, and Pascal as well as C and MASM.
Changed status display to be easier to read.
930115 - Version 3.24: Converted document to WordPerfect 5.1 and
rewrote much of it. Provide document in standard
release that can either be viewed on-line or printed.
930110 - Version 3.23: Added support for R= and W= commands.
Fixed handling of CLK.INI file so that we don't try to
update it if it is read only or is in a read-only
sub-directory. We also don't update it if we can't
find the [clk] section as it may be someone else's
file.
930106 - Version 3.22: Fixed bug in CLK.EXE that caused it to
move the CLK.INI file to the root directory.
930104 - Version 3.21: Fixed bug in CLOCK.SYS expecting zero for
100ths of seconds from CMOS clock but some BIOSs don't
zero the register. Fixed bug in CLK with synchroniza-
tion algorithm not correctly waiting for a new second.
930102 - Version 3.20: Add support for a command file, automat-
ic adjustment, and improved synchronization. My thanks
to Eric Smith for the ideas that lead to these enhance-
ments.
921230 - Version 3.11: Simplified logic in CLOCK.SYS for check-
ing if calendar clock should be read.
921229 - Version 3.10: Add support for constant synchronization
with calendar clock. Fix bug in calculating dates near
the end of leap years.
921226 - Version 3.02: Recompile CLK.EXE and CLKDEMO.EXE to only
use 8088 instructions. Version 3.01 inadvertently com-
72
CLOCK Version 3.47 April 10, 1993
piled with 80286 instructions which can lock up 8088
systems.
921221 - Version 3.01: Fixed a couple of bugs in beta test
version 3.00 with non-PC/AT clocks. Added logic to CLK
to display the pre-defined time zones on errors or
request.
921219 - Version 3.00: Added support for automatic time zone and
daylight savings time adjustment. CLOCK.SYS now has
the ability to manage the DOS real time clock and the
battery-protected clock separately. CLK.EXE is used to
convert a base value in the battery-protected clock to
a correct local time in the DOS clock.
920614 - Version 2.24: Fixed bug in probing of AT&T 6300 clocks.
Some of the clocks do not set AL on successful opera-
tion.
920604 - Version 2.23: Fixed bug causing fall through into
memory probing when only I/O probing was wanted.
920411 - Version 2.22: Changed order of probing to probe memory-
mapped clocks last as they are being spuriously found
on some Tandy systems.
920401 - Version 2.21: Changed pattern of I/O address probing
to probe all possible I/O addresses for one type (e.g.,
4) before trying any for another type. Try to avoid
finding the wrong type. Added the type B clock to the
type 8 probe.
920328 - Version 2.20: Changed order of I/O address probing for
clock types 4, 6, and 7 to avoid, where possible,
accessing other boards. Most commonly used I/O clock
addresses, I hope, are now probed first.
920322 - Version 2.19: Improved probing for I/O clocks to check
that legal values are found in all the data registers.
Several of the I/O clocks use operation sequences so
much like each other that it is possible to choose the
wrong one if we don't actually read the time and date
and see if the values are legal. This approach to
probing may possibly result in not finding a clock that
is present but that has been totally reset. Such a
clock should be found on a second try to boot with
CLOCK.SYS as the counters will have advanced by then.
73
CLOCK Version 3.47 April 10, 1993
920320 - Version 2.18: Added probing for generic PC/AT type
clock on systems that don't have the PC/AT signature in
the BIOS.
920307 - Version 2.17: Added Hyundai 8088 clock.
920112 - Version 2.16: Added AT&T 6300 clock.
920111 - Version 2.15: Fixed memory address used by one type of
SMT No-Slot clock.
920105 - Version 2.14: Added support for a wider variety of
memory mapped clocks including the SMT (Systems Manu-
facturing Technology) No-Slot clocks.
911208 - Version 2.13: Add probing for Vendex Headstart Turbo-
888-XT system and any other I/O clock at 300H. Change
I/O clock probing logic to make it less likely to find
the wrong type by accident.
911129 - Version 2.12: Fix handling of Quadram clocks (type 9).
They can only set seconds to zero so generate an error
if anyone tries to set the seconds to any other value.
911128 - Version 2.11: Fix bug in handling clock type 9,
Quadram clocks that left clock turned off after opera-
tions. Also fix bug in busy determination for clock
types 4 and 6 that could result in a decision that the
clock was not operational.
911121 - Version 2.10: Add clock types 6 ,7 and 9. Add type 8
to do specific probing for the various I/O bus clock
types.
911109 - Version 2.05: Fix bug in leap day handling for I/O
clocks. Fix bug that caused hung systems when setting
the date or time on Z-18x portables.
911026 - Version 2.04: Add support for I/O clocks at addresses
240H and 340H. Reduce resident memory required by
clock driver to only that required for specific clock
type.
911021 - Version 2.03: Change handling of new day flag from
BIOS to accommodate BIOSs that indicate multiple days
have passed.
74
CLOCK Version 3.47 April 10, 1993
911020 - Version 2.02: Fix bug in returning date on clock read
functions. Added message in automatic determination to
indicate type found.
911010 - Version 2.01: Added automatic determination of
Mitsubishi 8088 PC clocks. Fixed handler to keep the
BIOS counter set properly for programs that read it
directly. Also returns a finer granularity value
(100ths of seconds) on reads.
911009 - Version 2.00: Modified clock driver to support addi-
tional clock types. Thanks to Eric Smith (no relation)
for help in finding out how the Zenith PC clock worked.
911005 - Version 1.20: Changed prologue and epilogue to conform
to DOS 5.00 documentation. Seems to work OK with DOS
5.0 without the changes, but we might as well be con-
sistent to save problems later.
910903 - Version 1.10: Added display of current date and time
when initializing.
910518 - CLOCK version 1.00. Initial version developed at the
request of a friend with a Sperry PC/HT who wanted to
move to DOS 4.01.
1984 - Write clock device driver for AST clock for IBM PC-1.
This serves as the introduction to what device drivers
and especially the CLOCK$ driver are all about.
75
